trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r785153 - in /websites/staging/trafficserver/trunk/content/docs/trunk: ./ sdk/io-guide/ sdk/io-guide/guide-to-cache-api/
Date Wed, 09 Feb 2011 23:51:46 GMT
Author: buildbot
Date: Wed Feb  9 23:51:46 2011
New Revision: 785153

Log:
Staging update by buildbot

Modified:
    websites/staging/trafficserver/trunk/content/docs/trunk/STATUS
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/index.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/io-buffers.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/net-vconnections.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/transformations.en.html
    websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/vios.en.html

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/STATUS
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/STATUS (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/STATUS Wed Feb  9 23:51:46 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: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,27 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="how-to-do-a-cache-remove">Prev</a> - How to Do a Cache Remove</p>
+<p>Example - <a href="example">Next</a></p>
+<h3 id="Errors">Errors</h3>
+<p>Errors pertaining to the failure of various cache operations are indicated 
+by <code>TSCacheError</code> (enumeration). They are as follows:</p>
+<ul>
+<li>
+<p><code>TS_CACHE_ERROR_NO_DOC</code> - the key does not match a cached resource</p>
+</li>
+<li>
+<p><code>TS_CACHE_ERROR_DOC_BUSY</code> - e.g, another continuation could be writing to 
+the cache location</p>
+</li>
+<li>
+<p><code>TS_CACHE_ERROR_NOT_READY</code> - the cache is not ready</p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,62 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="errors">Prev</a> - Errors</p>
+<p>Chapter 16. Plugin Management - <a href="../../plugin-management">Next</a></p>
+<h3 id="Example">Example</h3>
+<p>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 (<code>cache_bufp</code>) to hold the document; meanwhile, use 
+<code>TSVConnCachedObjectSizeGet</code> to find out the actual size of the document (<code>content_length</code>). 
+Then, issue <code>TSVConnRead</code> to read the document with the total data length 
+required as <code>content_length</code>. Assume the following data:</p>
+<div class="codehilite"><pre>    <span class="n">TSIOBuffer</span>       <span class="n">cache_bufp</span> <span class="o">=</span> <span class="n">TSIOBufferCreate</span> <span class="p">();</span>
+    <span class="n">TSIOBufferReader</span> <span class="n">cache_readerp</span> <span class="o">=</span> <span class="n">TSIOBufferReaderAlloc</span> <span class="p">(</span><span class="n">out_bufp</span><span class="p">);</span>
+    <span class="n">TSVConn</span>          <span class="n">cache_vconnp</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
+    <span class="n">TSVIO</span>            <span class="n">cache_vio</span> <span class="o">=</span> <span class="nb">NULL</span><span class="p">;</span>
+    <span class="kt">int</span>               <span class="n">content_length</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
+</pre></div>
+
+
+<p>In the <code>TS_CACHE_OPEN_READ</code> handler:</p>
+<div class="codehilite"><pre><span class="n">cache_vconnp</span> <span class="o">=</span> <span class="p">(</span><span class="n">TSVConn</span><span class="p">)</span> <span class="n">data</span><span class="p">;</span>
+    <span class="n">TSVConnCachedObjectSizeGet</span> <span class="p">(</span><span class="n">cache_vconnp</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">content_length</span><span class="p">);</span>
+    <span class="n">cache_vio</span> <span class="o">=</span> <span class="n">TSVConnRead</span> <span class="p">(</span><span class="n">cache_vconn</span><span class="p">,</span> <span class="n">contp</span><span class="p">,</span> <span class="n">cache_bufp</span><span class="p">,</span> <span class="n">content_length</span><span class="p">);</span>
+</pre></div>
+
+
+<p>In the <code>TS_EVENT_VCONN_READ_READY</code> handler:</p>
+<div class="codehilite"><pre><span class="p">(</span><span class="n">usual</span> <span class="n">VCONN_READ_READY</span> <span class="n">handler</span> <span class="n">logic</span><span class="p">)</span>
+<span class="kt">int</span> <span class="n">nbytes</span> <span class="o">=</span> <span class="n">TSVIONBytesGet</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">ntodo</span>  <span class="o">=</span> <span class="n">TSVIONTodoGet</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+<span class="kt">int</span> <span class="n">ndone</span>  <span class="o">=</span> <span class="n">TSVIONDoneGet</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+<span class="p">(</span><span class="n">consume</span> <span class="n">data</span> <span class="n">in</span> <span class="n">cache_bufp</span><span class="p">)</span>
+<span class="n">TSVIOReenable</span> <span class="p">(</span><span class="n">cache_vio</span><span class="p">);</span>
+</pre></div>
+
+
+<p>Do not try to get continuations or VIOs from <code>TSVConn</code> 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:</p>
+<ul>
+<li>
+<p><code>TSVConnWriteVIOGet</code></p>
+</li>
+<li>
+<p><code>TSVConnReadVIOGet</code></p>
+</li>
+<li>
+<p><code>TSVConnClosedGet</code></p>
+</li>
+</ul>
+<p>APIs such as <code>TSVConnRead</code>, <code>TSVConnWrite</code>, <code>TSVConnClose</code>, <code>TSVConnAbort</code>, 
+and <code>TSVConnShutdown</code> can be used on any kind of vconnections.</p>
+<p>When you are finished:</p>
+<p><code>TSCacheKeyDestroy (key);</code></p>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit # {#ApacheTS™SoftwareDevelopersKit}</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,26 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit # {#ApacheTS™SoftwareDevelopersKit}</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="how-to-do-a-cache-write">Prev</a> - How to Do a Cache Write</p>
+<p>Errors - <a href="errors">Next</a></p>
+<h3 id="HowDoaCacheRemove">How to Do a Cache Remove</h3>
+<p>Use <code>TSCacheRemove</code> to remove items from the cache. Possible callback events 
+include:</p>
+<ul>
+<li>
+<p><code>TS_EVENT_CACHE_REMOVE</code> - the item was removed. There is no data payload for 
+this event.</p>
+</li>
+<li>
+<p><code>TS_EVENT_CACHE_REMOVE_FAILED</code> - indicates the cache was unable to remove 
+the item idetified by the cache key. <code>TSCacheError</code> data indicates why the 
+remove failed.</p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,27 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="../guide-to-cache-api">Prev</a> - Guide to the Cache API</p>
+<p>How to Do a Cache Remove - <a href="how-to-do-a-cache-remove">Next</a></p>
+<h3 id="HowDoaCacheWrite">How to Do a Cache Write</h3>
+<p>Use <code>TSCacheWrite</code> to write to a cache (see the <a href="../../new-protocol-plugins#AboutSampleProtocol">sample Protocol plugin</a>). 
+Possible callback events include:</p>
+<ul>
+<li>
+<p><code>TS_EVENT_CACHE_WRITE_READ</code> - 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.</p>
+</li>
+<li>
+<p><code>TS_EVENT_CACHE_OPEN_WRITE_FAILED</code> - 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 (<code>TSCacheError</code>).</p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,46 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="../io-buffers">Prev</a> - IO Buffers</p>
+<p>How to Do a Cache Write - <a href="how-to-do-a-cache-write">Next</a></p>
+<h2 id="GuideCacheAPI">Guide to the Cache API</h2>
+<p>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 <code>TSCacheKey</code>; 
+cache keys are created via <code>TSCacheKeyCreate</code>; keys are destroyed via <code>TSCacheKeyDestroy</code>. 
+Use <code>TSCacheKeyDigestSet</code> to set the hash of the cache key.</p>
+<p>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). </p>
+<p><strong>Example:</strong></p>
+<div class="codehilite"><pre>    <span class="k">const</span> <span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span><span class="n">key_name</span> <span class="o">=</span> <span class="s">&quot;example key name&quot;</span><span class="p">;</span>
+
+    <span class="n">TSCacheKey</span> <span class="n">key</span><span class="p">;</span>
+    <span class="n">TSCacheKeyCreate</span> <span class="p">(</span><span class="o">&amp;</span><span class="n">key</span><span class="p">);</span>
+    <span class="n">TSCacheKeyDigestSet</span> <span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="p">(</span><span class="kt">unsigned</span> <span class="kt">char</span> <span class="o">*</span><span class="p">)</span> <span class="n">key_name</span> <span class="p">,</span> <span class="n">strlen</span><span class="p">(</span><span class="n">key_name</span><span class="p">));</span>
+    <span class="n">TSCacheKeyDestroy</span> <span class="p">(</span><span class="n">key</span><span class="p">);</span>
+</pre></div>
+
+
+<h3 id="HowDoaCacheRead">How to Do a Cache Read</h3>
+<p><code>TSCacheRead</code> does not really read - it is used for lookups (see the sample 
+Protocol plugin). Possible callback events include:</p>
+<ul>
+<li>
+<p><code>TS_EVENT_CACHE_OPEN_READ</code> - 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.</p>
+</li>
+<li>
+<p><code>TS_EVENT_CACHE_OPEN_READ_FAILED</code> - 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 (<code>TSCacheError</code>). </p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/index.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/index.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/index.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,151 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="../actions-guide/hosts-lookup-api">Prev</a> - Hosts Lookup API</p>
+<p>Net Vconnections - <a href="net-vconnections">Next</a></p>
+<h2 id="IOGuide">IO Guide</h2>
+<p>This chapter contains the following sections:</p>
+<ul>
+<li><a href="#Vconnections">Vconnections</a></li>
+<li><a href="net-vconnections">Net Vconnections</a></li>
+<li><a href="transformations">Transformations</a></li>
+<li><a href="../http-transformation-plugin#VIOs">VIOs</a></li>
+<li><a href="../http-transformation-plugin#IOBuffers">IO Buffers</a></li>
+<li><a href="guide-to-cache-api">Guide to the Cache API</a><ul>
+<li><a href="guide-to-cache-api">How to Do a Cache Read</a></li>
+<li><a href="guide-to-cache-api">How to Do a Cache Write</a></li>
+<li><a href="guide-to-cache-api">How to Do a Cache Remove</a></li>
+<li><a href="guide-to-cache-api">Errors</a></li>
+<li><a href="guide-to-cache-api">Example</a></li>
+</ul>
+</li>
+</ul>
+<h2 id="Vconnections">Vconnections</h2>
+<h3 id="VconnectionsaUsersPerspective">Vconnections: a User's Perspective</h3>
+<p>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 <code>TSNetConnect)</code>. In the case of 
+transform plugins, the plugin creates a transformation vconnection viav <code>TSTransformCreate</code> 
+and then accesses the output vconnection using <code>TSTransformOutputVConnGet</code>. </p>
+<p>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.</p>
+<p>To issue a read or write operation, a user calls <code>TSVConnRead</code> or <code>TSVConnWrite</code>. 
+These two operations both return <code>VIO (TSVIO)</code>. The VIO describes the operation 
+being performed and how much progress has been made. Transform plugins initiate 
+output to the downstream vconnection by calling <code>TSVConnWrite</code>.</p>
+<p>A vconnection read or write operation is different from a normal UNIX <code>read(2)</code> 
+or <code>write(2)</code> 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 <code>INT64_MAX</code> (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 <code>read(2)</code> until one of the calls finally returns 
+<code>0</code> to indicate the end of stream was reached (indeed, the underlying implementation 
+of vconnections on UNIX still does issue those calls to <code>read(2)</code>, but the 
+interface does not expose that detail).</p>
+<p>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.</p>
+<p>One obvious issue is that the buffer passed to <code>TSVConnRead</code> and <code>TSVConnWrite</code> 
+won't be large enough - there is no reasonable way to make a buffer that can 
+hold <code>INT64_MAX</code> (9 quintillion) bytes! The secret is that vconnections engage 
+in a protocol whereby they signal to the user (via the continuation passed 
+to <code>TSVConnRead</code> and <code>TSVConnWrite</code>) 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 <code>TSVIOReenable</code> on the VIO describing the 
+operation. <code>TSVIOReenable</code> 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.</p>
+<p>The null transform plugin provides an example of how this is done. Below is 
+a prototype for <code>TSVConnWrite</code>:</p>
+<div class="codehilite"><pre> <span class="n">TSVIO</span> <span class="n">TSVConnWrite</span> <span class="p">(</span><span class="n">TSVConn</span> <span class="n">connp</span><span class="p">,</span> <span class="n">TSCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">TSIOBufferReader</span> <span class="n">readerp</span><span class="p">,</span> <span class="kt">int</span> <span class="n">nbytes</span><span class="p">)</span>
+</pre></div>
+
+
+<p>The <code>connp</code> is the vconnection the user is writing to and <code>contp</code> is the "user" -
+i.e., the continuation that <code>connp</code> calls back when it has emptied its 
+buffer and is ready for more data.</p>
+<p>The call made in the null transform plugin is:</p>
+<div class="codehilite"><pre>  <span class="n">TSVConnWrite</span> <span class="p">(</span><span class="n">output_conn</span><span class="p">,</span> <span class="n">contp</span><span class="p">,</span> <span class="n">data</span><span class="o">-&gt;</span><span class="n">output_reader</span><span class="p">,</span> <span class="n">TSVIONBytesGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">));</span>
+</pre></div>
+
+
+<p>In the example above, <code>contp</code> is the transformation vconnection that is writing 
+to the output vconnection. The number of bytes to be written is obtained from 
+<code>input_vio</code> by <code>TSVIONBytesGet</code>.</p>
+<p>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 <code>TSContCall</code>. 
+It passes the <code>TSVIO</code> describing the operation as the data parameter, and 
+one of the values below as the event parameter.</p>
+<dl>
+<dt><code>TS_EVENT_ERROR</code></dt>
+<dd>Indicates an error has occurred on the vconnection. This will happen for network 
+IO if the underlying <code>read(2)</code> or <code>write(2)</code> call returns an error.</dd>
+<dt><code>TS_EVENT_VCONN_READ_READY</code></dt>
+<dd>The vconnection has placed data in the buffer passed to an <code>TSVConnRead</code> 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.</dd>
+<dt><code>TS_EVENT_VCONN_WRITE_READY</code></dt>
+<dd>The vconnection has removed data from the buffer passed to an <code>TSVConnWrite</code> 
+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. </dd>
+<dt><code>TS_EVENT_VCONN_READ_COMPLETE</code></dt>
+<dd>The vconnection has read all the bytes specified by an <code>TSVConnRead</code> operation. 
+The vconnection can now be used to initiate a new IO operation.</dd>
+<dt><code>TS_EVENT_VCONN_WRITE_COMPLETE</code></dt>
+<dd>The vconnection has written all the bytes specified by an <code>TSVConnWrite</code> operation 
+and can now be used to initiate a new IO operation.</dd>
+<dt><code>TS_EVENT_VCONN_EOS</code></dt>
+<dd>An attempt was made to read past the end of the stream of bytes during the 
+handling of an <code>TSVConnRead</code> 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 <code>TSVConnRead</code>. 
+A common case where this occurs is when the user specifies that <code>INT64_MAX</code> 
+bytes are to be read from a network connection.</dd>
+</dl>
+<p>For example: the null transform plugin's transformation receives <code>TS_EVENT_VCONN_WRITE_READY</code> 
+and <code>TS_EVENT_VCONN_WRITE_COMPLETE</code> events from the downstream vconnection 
+as a result of the call to <code>TSVConnWrite</code>.</p>
+<p>After using a vconnection, the user must call <code>TSVConnClose</code> or <code>TSVConnAbort</code>. 
+While both calls indicate that the vconnection can destroy itself, <code>TSVConnAbort</code> 
+should be used when the connection is being closed abnormally. After a call 
+to <code>TSVConnClose</code> or <code>TSVConnAbort</code>, the user will not be called back by 
+the vconnection again.</p>
+<p>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 <code>TSVConnShutdown</code> 
+function, which shuts down either the read or write portion of a vconnection. 
+<em>Shutdown</em> 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 <code>TS_EVENT_VCONN_WRITE_READY</code> 
+or <code>TS_EVENT_VCONN_WRITE_COMPLETE</code> events will not be produced. In the null 
+transform plugin, the write operation is shut down with a call to <code>TSVConnShutdown</code>. 
+To learn how vconnections are used in transformation plugins, see <a href="../http-transformation-plugin#WritingContentTransformPlugins">Writing 
+Content Transform Plugins</a>.</p>
+<p>The vconnection functions are listed below:</p>
+<ul>
+<li><a href="link/to/doxygen">TSVConnAbort</a></li>
+<li><a href="link/to/doxygen">TSVConnClose</a></li>
+<li><a href="link/to/doxygen">TSVConnClosedGet</a></li>
+<li><a href="link/to/doxygen">TSVConnRead</a></li>
+<li><a href="link/to/doxygen">TSVConnReadVIOGet</a></li>
+<li><a href="link/to/doxygen">TSVConnShutdown</a></li>
+<li><a href="link/to/doxygen">TSVConnWrite</a></li>
+<li><a href="link/to/doxygen">TSVConnWriteVIOGet</a></li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/io-buffers.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/io-buffers.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/io-buffers.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,40 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="vios">Prev</a> - VIOs</p>
+<p>Guide to the Cache API - <a href="guide-to-cache-api">Next</a></p>
+<h2 id="IOBuffers">IO Buffers</h2>
+<p>The IO buffer data structure is the building block of the vconnection abstraction. 
+An <strong>IO buffer</strong> (<code>TSIOBuffer</code>) is composed of a list of buffer blocks that 
+point to buffer data. Both the buffer block (<code>TSIOBufferBlock</code>) and buffer 
+data (<code>TSIOBufferData</code>) 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 <code>TSIOBufferCopy</code>, since Traffic 
+Server must only copy pointers and adjust reference counts appropriately (and 
+doesn't actually copy any data).</p>
+<p>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 <code>TSIOBufferReader</code> data structure. Since only a single 
+writer is allowed, there is no corresponding <code>TSIOBufferWriter</code> 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 <a href="link/to/doxygen"><code>TSIOBufferBlockReadStart</code></a>.</p>
+<p>Additional information about IO buffer functions:</p>
+<ul>
+<li>
+<p>The <code>TSIOBufferReader</code> data structure tracks how much data in <code>TSIOBuffer</code> 
+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 <code>TSIOBuffer</code>, 
+you must allocate an <code>TSIOBufferReader</code>).</p>
+</li>
+<li>
+<p>Bytes that have already been read may not necessarily be freed within the
+<code>TSIOBuffer</code>. To consume bytes that have been read, you must call <code>TSIOBufferConsume</code>.</p>
+</li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/net-vconnections.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/net-vconnections.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/net-vconnections.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,22 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="../io-guide">Prev</a> - IO Guide</p>
+<p>Transformations - <a href="transformations">Next</a></p>
+<h2 id="NetVconnections">Net Vconnections</h2>
+<p>A <strong>network</strong> <strong>vconnection</strong> (or<strong> netvconnection</strong>) is a wrapper around a 
+TCP socket that enables the socket to work within the Traffic Server vconnection 
+framework. See <a href="IOGuide.html#Vconnections">vconnections</a> for more information 
+about the Traffic Server abstraction for doing asynchronous IO.</p>
+<p>The netvconnection functions are listed below:</p>
+<ul>
+<li><a href="NetvconnectionFunctions.html#TSNetAccept">TSNetAccept</a></li>
+<li><a href="TSNetConnect.html">TSNetConnect</a></li>
+</ul>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/transformations.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/transformations.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/transformations.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,151 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="net-vconnections">Prev</a> - Net Vconnections</p>
+<p>VIOs - <a href="vios">Next</a></p>
+<h2 id="Transformations">Transformations</h2>
+<h3 id="VconnectionImplementorsView">The Vconnection Implementor's View</h3>
+<p>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 <code>TSVConnRead</code> or <code>TSVConnWrite</code>. The implementor, in turn, gets a handle 
+on the VIO operation by examining the VIO returned by <code>TSVConnReadVIOGet</code> 
+or <code>TSVConnWriteVIOGet</code> (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).</p>
+<p>For example, the null transform plugin's transformation examines the input 
+VIO by calling:</p>
+<div class="codehilite"><pre> <span class="n">input_vio</span> <span class="o">=</span> <span class="n">TSVConnWriteVIOGet</span> <span class="p">(</span><span class="n">contp</span><span class="p">);</span>
+</pre></div>
+
+
+<p>where <code>contp</code> is the transformation.</p>
+<p>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.</p>
+<p>It is common for the handler function for all vconnections to look similar. 
+Their basic form looks something like the code fragment below:</p>
+<div class="codehilite"><pre><span class="kt">int</span>
+<span class="nf">vconnection_handler</span> <span class="p">(</span><span class="n">TSCont</span> <span class="n">contp</span><span class="p">,</span> <span class="n">TSEvent</span> <span class="n">event</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">edata</span><span class="p">)</span>
+<span class="p">{</span>
+<span class="k">if</span> <span class="p">(</span><span class="n">TSVConnClosedGet</span> <span class="p">(</span><span class="n">contp</span><span class="p">))</span> <span class="p">{</span>
+        <span class="cm">/* Destroy any vconnection specific data here. */</span>
+        <span class="n">TSContDestroy</span> <span class="p">(</span><span class="n">contp</span><span class="p">);</span>
+        <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+   <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
+        <span class="cm">/* Handle the incoming event */</span>
+   <span class="p">}</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>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 <code>TSVConnClose</code> 
+does not simply just destroy the vconnection.</p>
+<p>Vconnections are state machines that are animated by the events they receive. 
+An event is sent to the vconnection whenever an <code>TSVConnRead</code>, <code>TSVConnWrite</code>, 
+<code>TSVConnClose</code>, <code>TSVConnShutdown</code>, or <code>TSVIOReenable</code> call is performed. 
+<code>TSVIOReenable</code> 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 <code>TSVConnClose</code> is called, the vconnection is sent an immediate 
+event (<code>TS_EVENT_IMMEDIATE</code>). For every event the vconnection receives, it 
+needs to check its closed flag to see if it has been closed. Similarly, when 
+<code>TSVIOReenable</code> 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.</p>
+<p>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 <code>TS_EVENT_VCONN_WRITE_READY</code>, 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.</p>
+<h4 id="TransformationVConnection">Transformation VConnection</h4>
+<p>A <a href="HTTPTransformationPlugins.html#Transformations">transformation</a> 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.</p>
+<p>A transformation can modify either the data stream being sent <em>to</em> an HTTP 
+client (e.g. the document) or the data stream being sent <em>from</em> an HTTP client 
+(e.g. post data). To do this, the transformation should hook on to one of the 
+following hooks:</p>
+<ul>
+<li>
+<p><code>TS_HTTP_REQUEST_TRANSFORM_HOOK</code></p>
+</li>
+<li>
+<p><code>TS_HTTP_RESPONSE_TRANSFORM_HOOK</code></p>
+</li>
+</ul>
+<p>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.</p>
+<p>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 <code>TS_EVENT_WRITE_COMPLETE</code> event. Transformations cannot send 
+the <code>TS_EVENT_VCONN_WRITE_COMPLETE</code> event to the upstream vconnection unless 
+they are finished consuming all incoming data. If <code>TS_EVENT_VCONN_WRITE_COMPLETE</code> 
+is sent prematurely, then certain internal Traffic Server data structures will 
+not be deallocated, thereby causing a memory leak.</p>
+<p>Here's how to make sure that all incoming data is consumed:</p>
+<ul>
+<li>
+<p>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 
+<code>null-transform.c</code>:</p>
+<div class="codehilite"><pre><span class="n">TSIOBufferCopy</span> <span class="p">(</span><span class="n">TSVIOBufferGet</span> <span class="p">(</span><span class="n">data</span><span class="o">-&gt;</span><span class="n">output_vio</span><span class="p">),</span>
+<span class="n">TSVIOReaderGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">),</span> <span class="n">towrite</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+<span class="cm">/* Tell the read buffer that we have read the data and are no longer interested in it. */</span>
+<span class="n">TSIOBufferReaderConsume</span> <span class="p">(</span><span class="n">TSVIOReaderGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">),</span> <span class="n">towrite</span><span class="p">);</span>
+<span class="cm">/* Modify the input VIO to reflect how much has been read.*/</span>
+<span class="n">TSVIONDoneSet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">,</span> <span class="n">TSVIONDoneGet</span> <span class="p">(</span><span class="n">input_vio</span><span class="p">)</span> <span class="o">+</span> <span class="n">towrite</span><span class="p">);</span>
+</pre></div>
+
+
+</li>
+<li>
+<p>Before sending <code>TS_EVENT_VCONN_WRITE_COMPLETE</code>, your transformation should 
+check the number of bytes remaining in the upstream vconnection's write VIO 
+(input VIO) using the function <code>TSVIONTodoGet</code> (<code>input_vio</code>). This value should 
+go to zero when all of the upstream data is consumed (`TSVIONTodoGet = nbytes </p>
+</li>
+<li>ndone<code>). Do not send</code>TS_EVENT_VCONN_WRITE_COMPLETE<code>events if</code>TSVIONTodoGet<code>is greater than zero.
+The transformation passes data out of itself by using the output vconnection 
+retrieved by</code>TSTransformOutputVConnGet<code>. 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</code>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.</li>
+</ul>
+<p>The transformation functions are:
+<em> <a href="link/to/doxygen">TSTransformCreate</a>
+</em> <a href="link/to/doxygen">TSTransformOutputVConnGet</a></p>
   </div>
 
   <div id="footer">

Modified: websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/vios.en.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/vios.en.html (original)
+++ websites/staging/trafficserver/trunk/content/docs/trunk/sdk/io-guide/vios.en.html Wed Feb  9 23:51:46 2011
@@ -6,8 +6,8 @@
     
     <link rel="stylesheet" href="/styles/pygments_style.css" />
     
-    <title></title>
-    
+    <title>Apache Traffic Server™ Software Developers Kit</title>
+    <!-- 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 &quot;License&quot;); 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 &quot;AS IS&quot; 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. -->
   </head>
 
   <body>
@@ -15,11 +15,46 @@
 	    <span id="ts_logo">
 		  <a href="http://trafficserver.apache.org/"><img alt="Apache Traffic Server" src="/images/ts75.png" /></a>
 	  </span>
-	    <h1></h1>
+	    <h1>Apache Traffic Server™ Software Developers Kit</h1>
     </div>
 
   <div id="content">
-      
+      <p><a href="transformations">Prev</a> - Transformations</p>
+<p>IO Buffers - <a href="io-buffers">Next</a></p>
+<h2 id="VIOs">VIOs</h2>
+<p>A <strong>VIO</strong>, or <strong>virtual IO</strong>, 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.</p>
+<p>The <code>TSVIO</code> data structure itself is opaque, but it could be defined as follows: </p>
+<div class="codehilite"><pre><span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
+    <span class="n">TSCont</span> <span class="n">continuation</span><span class="p">;</span>
+    <span class="n">TSVConn</span> <span class="n">vconnection</span><span class="p">;</span>
+    <span class="n">TSIOBufferReader</span> <span class="n">reader</span><span class="p">;</span>
+    <span class="n">TSMutex</span> <span class="n">mutex</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">nbytes</span><span class="p">;</span>
+    <span class="kt">int</span> <span class="n">ndone</span><span class="p">;</span>
+<span class="p">}</span> <span class="o">*</span><span class="n">TSVIO</span><span class="p">;</span>
+</pre></div>
+
+
+<p>The VIO functions below access and modify various parts of the data structure. </p>
+<ul>
+<li><a href="link/to/doxygen">TSVIOBufferGet</a></li>
+<li><a href="link/to/doxygen">TSVIOVConnGet</a></li>
+<li><a href="link/to/doxygen">TSVIOContGet</a></li>
+<li><a href="link/to/doxygen">TSVIOMutexGet</a></li>
+<li><a href="link/to/doxygen">TSVIONBytesGet</a></li>
+<li><a href="link/to/doxygen">TSVIONBytesSet</a></li>
+<li><a href="link/to/doxygen">TSVIONDoneGet</a></li>
+<li><a href="link/to/doxygen">TSVIONDoneSet</a></li>
+<li><a href="link/to/doxygen">TSVIONTodoGet</a></li>
+<li><a href="link/to/doxygen">TSVIOReaderGet</a></li>
+<li><a href="link/to/doxygen">TSVIOReenable</a></li>
+</ul>
   </div>
 
   <div id="footer">



Mime
View raw message