You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by an...@apache.org on 2009/10/30 00:23:36 UTC

svn commit: r831152 [29/37] - in /incubator/trafficserver/site/trunk/docs: ./ admin/ admin/images/ sdk/ sdk/css/ sdk/images/ sdk/images/docbook/ sdk/js/

Propchange: incubator/trafficserver/site/trunk/docs/sdk/MimeHeadersFunctions.html
------------------------------------------------------------------------------
    svn:keywords = Id

Added: incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html (added)
+++ incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html Thu Oct 29 23:23:25 2009
@@ -0,0 +1,108 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Chapter 9. Miscellaneous Interface Guide</title>
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/reset/reset-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/fonts/fonts-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc-chunk.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="up" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="prev" href="HTTPAlternateSelection.html" title="HTTP Alternate Selection">
+<link rel="next" href="INKfopenFamily.html" title="The INKfopen Family">
+<link rel="preface" href="Preface.html" title="Preface">
+<link rel="chapter" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="chapter" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="index" href="CreatingTSPlugins.html#id372630" title="Index">
+<link rel="chapter" href="ch03.html" title="Chapter 3. Remap Plugin">
+<link rel="chapter" href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">
+<link rel="chapter" href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">
+<link rel="chapter" href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">
+<link rel="chapter" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="chapter" href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">
+<link rel="chapter" href="MiscellaneousInterfaceGuide.html" title="Chapter 9. Miscellaneous Interface Guide">
+<link rel="chapter" href="HTTPHeaders.html" title="Chapter 10. HTTP Headers">
+<link rel="chapter" href="MutexGuide.html" title="Chapter 11. Mutex Guide">
+<link rel="chapter" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="chapter" href="PluginConfigurations.html" title="Chapter 13. Plugin Configurations">
+<link rel="chapter" href="ActionsGuide.html" title="Chapter 14. Actions Guide">
+<link rel="chapter" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="chapter" href="PluginManagement.html" title="Chapter 16. Plugin Management">
+<link rel="chapter" href="AddingStatistics.html" title="Chapter 17. Adding Statistics">
+<link rel="chapter" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="appendix" href="App_SampleSourceCode.html" title="Appendix A. Sample Source Code">
+<link rel="appendix" href="App_DeprecatedFunctions.html" title="Appendix B. Deprecated Functions">
+<link rel="appendix" href="App_Troubleshooting.html" title="Appendix C. Troubleshooting Tips">
+<link rel="appendix" href="FunctionIndex.html" title="Appendix D. Function Index">
+<link rel="appendix" href="TypeIndex.html" title="Appendix E. Type Index">
+<link rel="index" href="ConceptIndex.html" title="Index">
+<link rel="section" href="MiscellaneousInterfaceGuide.html#Interface_Debugging" title="Debugging Functions">
+<link rel="section" href="INKfopenFamily.html" title="The INKfopen Family">
+<link rel="section" href="MemoryAllocation.html" title="Memory Allocation">
+<link rel="section" href="Interface_ThreadFunctions.html" title="Thread Functions">
+<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/yahoo/yahoo-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/event/event-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js"></script><script type="text/javascript" src="js/tocnodes.js"></script><script type="text/javascript" src="js/toc.js"></script><script type="text/javascript">
+    document.write("<style> div.toc {display: none} </style>"); 
+  </script>
+</head>
+<body>
+<div class="doctitle">
+<a href="index.html">Home</a>
+<img src="images/docbook/ts75.png"><h1 class="doctitle">Traffic Server Software Developers Kit</h1>
+</div>
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="HTTPAlternateSelection.html">Prev</a> — HTTP Alternate Selection</div>
+<div class="navnext">The INKfopen Family — <a accesskey="n" href="INKfopenFamily.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="MiscellaneousInterfaceGuide"></a>Chapter 9. Miscellaneous Interface Guide</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="MiscellaneousInterfaceGuide.html#Interface_Debugging">Debugging Functions</a></span></dt>
+<dt><span class="section"><a href="INKfopenFamily.html">The INKfopen Family</a></span></dt>
+<dt><span class="section"><a href="MemoryAllocation.html">Memory Allocation</a></span></dt>
+<dt><span class="section"><a href="Interface_ThreadFunctions.html">Thread Functions</a></span></dt>
+</dl>
+</div>
+<p>Most of the functions in the Traffic Server API provide an interface
+    to specific code modules within Traffic Server. The miscellaneous
+    functions described in this chapter provide some useful general
+    capabilities:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="DebuggingFunctions.html" title="Debugging Functions">“Debugging Functions”</a></p></li>
+<li><p><a href="INKfopenFamily.html" title="The INKfopen Family">“The INKfopen Family”</a></p></li>
+<li><p><a href="MemoryAllocation.html" title="Memory Allocation">“Memory Allocation”</a></p></li>
+<li><p><a href="ThreadFunctions.html" title="Thread Functions">“Thread Functions”</a></p></li>
+</ul></div>
+<p>While the C library already provides functions such as
+    <code class="function">printf</code>, <code class="function">malloc</code>, and
+    <code class="function">fopen</code> that perform these tasks, the Traffic Server
+    API versions overcome various C library limitations (such as portability
+    to all Traffic Server-supported platforms).</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="Interface_Debugging"></a>Debugging Functions</h2></div></div></div>
+<p>Debugging functions</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="DebuggingFunctions.html#INKDebug" title="INKDebug">“INKDebug”</a> prints out a formatted statement
+          if you are running Traffic Server in debug mode.</p></li>
+<li><p><a href="INKIsDebugTagSet.html" title="INKIsDebugTagSet">“INKIsDebugTagSet”</a> finds out if a debug tag
+          is set. If the debug tag is set, Traffic Server prints out any debug
+          statements associated to the debug tag.</p></li>
+<li><p><a href="INKError.html" title="INKError">“INKError”</a> prints error messages to Traffic
+          Server’s error log</p></li>
+<li><p><a href="INKAssert.html" title="INKAssert">“INKAssert”</a> allows the use of assertion in a
+          plugin.</p></li>
+<li><p><a href="INKReleaseAssert.html" title="INKReleaseAssert">“INKReleaseAssert”</a> allows the use of
+          assertion in a plugin.</p></li>
+</ul></div>
+</div>
+</div>
+</body>
+</html>

Propchange: incubator/trafficserver/site/trunk/docs/sdk/MiscellaneousInterfaceGuide.html
------------------------------------------------------------------------------
    svn:keywords = Id

Added: incubator/trafficserver/site/trunk/docs/sdk/MutexFunctions.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/MutexFunctions.html?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/MutexFunctions.html (added)
+++ incubator/trafficserver/site/trunk/docs/sdk/MutexFunctions.html Thu Oct 29 23:23:25 2009
@@ -0,0 +1,85 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Mutex Functions</title>
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/reset/reset-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/fonts/fonts-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc-chunk.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="up" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="prev" href="MimeHeadersFunctions.html" title="MIIME Headers">
+<link rel="next" href="INKMutexLock.html" title="INKMutexLock">
+<link rel="preface" href="Preface.html" title="Preface">
+<link rel="chapter" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="chapter" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="index" href="CreatingTSPlugins.html#id372630" title="Index">
+<link rel="chapter" href="ch03.html" title="Chapter 3. Remap Plugin">
+<link rel="chapter" href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">
+<link rel="chapter" href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">
+<link rel="chapter" href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">
+<link rel="chapter" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="chapter" href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">
+<link rel="chapter" href="MiscellaneousInterfaceGuide.html" title="Chapter 9. Miscellaneous Interface Guide">
+<link rel="chapter" href="HTTPHeaders.html" title="Chapter 10. HTTP Headers">
+<link rel="chapter" href="MutexGuide.html" title="Chapter 11. Mutex Guide">
+<link rel="chapter" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="chapter" href="PluginConfigurations.html" title="Chapter 13. Plugin Configurations">
+<link rel="chapter" href="ActionsGuide.html" title="Chapter 14. Actions Guide">
+<link rel="chapter" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="chapter" href="PluginManagement.html" title="Chapter 16. Plugin Management">
+<link rel="chapter" href="AddingStatistics.html" title="Chapter 17. Adding Statistics">
+<link rel="chapter" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="appendix" href="App_SampleSourceCode.html" title="Appendix A. Sample Source Code">
+<link rel="appendix" href="App_DeprecatedFunctions.html" title="Appendix B. Deprecated Functions">
+<link rel="appendix" href="App_Troubleshooting.html" title="Appendix C. Troubleshooting Tips">
+<link rel="appendix" href="FunctionIndex.html" title="Appendix D. Function Index">
+<link rel="appendix" href="TypeIndex.html" title="Appendix E. Type Index">
+<link rel="index" href="ConceptIndex.html" title="Index">
+<link rel="subsection" href="MutexFunctions.html#INKMutexCreate" title="INKMutexCreate">
+<link rel="subsection" href="INKMutexLock.html" title="INKMutexLock">
+<link rel="subsection" href="INKMutexLockTry.html" title="INKMutexLockTry">
+<link rel="subsection" href="INKMutexUnlock.html" title="INKMutexUnlock">
+<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/yahoo/yahoo-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/event/event-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js"></script><script type="text/javascript" src="js/tocnodes.js"></script><script type="text/javascript" src="js/toc.js"></script><script type="text/javascript">
+    document.write("<style> div.toc {display: none} </style>"); 
+  </script>
+</head>
+<body>
+<div class="doctitle">
+<a href="index.html">Home</a>
+<img src="images/docbook/ts75.png"><h1 class="doctitle">Traffic Server Software Developers Kit</h1>
+</div>
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="MimeHeadersFunctions.html">Prev</a> — MIIME Headers</div>
+<div class="navnext">INKMutexLock — <a accesskey="n" href="INKMutexLock.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="MutexFunctions"></a>Mutex Functions</h2></div></div></div>
+<p></p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKMutexCreate"></a>INKMutexCreate</h3></div></div></div>
+<p>Creates a new <code class="code">INKMutex</code>.</p>
+<div class="variablelist"><dl>
+<dt><span class="term">Prototype</span></dt>
+<dd><p><code class="code">INKMutex INKMutexCreate (void)</code></p></dd>
+<dt><span class="term">Description</span></dt>
+<dd><p>Creates a new INKMutex.</p></dd>
+<dt><span class="term">Returns</span></dt>
+<dd>
+<p>A handle to the newly created mutex.</p>
+<p><code class="code">INK_ERROR_PTR</code> if error.</p>
+</dd>
+<dt><span class="term">First release</span></dt>
+<dd><p>Traffic Server 3.0</p></dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>

Propchange: incubator/trafficserver/site/trunk/docs/sdk/MutexFunctions.html
------------------------------------------------------------------------------
    svn:keywords = Id

Added: incubator/trafficserver/site/trunk/docs/sdk/MutexGuide.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/MutexGuide.html?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/MutexGuide.html (added)
+++ incubator/trafficserver/site/trunk/docs/sdk/MutexGuide.html Thu Oct 29 23:23:25 2009
@@ -0,0 +1,425 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Chapter 11. Mutex Guide</title>
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/reset/reset-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/fonts/fonts-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc-chunk.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="up" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="prev" href="MIMEHeaders.html" title="MIME Headers">
+<link rel="next" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="preface" href="Preface.html" title="Preface">
+<link rel="chapter" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="chapter" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="index" href="CreatingTSPlugins.html#id372630" title="Index">
+<link rel="chapter" href="ch03.html" title="Chapter 3. Remap Plugin">
+<link rel="chapter" href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">
+<link rel="chapter" href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">
+<link rel="chapter" href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">
+<link rel="chapter" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="chapter" href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">
+<link rel="chapter" href="MiscellaneousInterfaceGuide.html" title="Chapter 9. Miscellaneous Interface Guide">
+<link rel="chapter" href="HTTPHeaders.html" title="Chapter 10. HTTP Headers">
+<link rel="chapter" href="MutexGuide.html" title="Chapter 11. Mutex Guide">
+<link rel="chapter" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="chapter" href="PluginConfigurations.html" title="Chapter 13. Plugin Configurations">
+<link rel="chapter" href="ActionsGuide.html" title="Chapter 14. Actions Guide">
+<link rel="chapter" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="chapter" href="PluginManagement.html" title="Chapter 16. Plugin Management">
+<link rel="chapter" href="AddingStatistics.html" title="Chapter 17. Adding Statistics">
+<link rel="chapter" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="appendix" href="App_SampleSourceCode.html" title="Appendix A. Sample Source Code">
+<link rel="appendix" href="App_DeprecatedFunctions.html" title="Appendix B. Deprecated Functions">
+<link rel="appendix" href="App_Troubleshooting.html" title="Appendix C. Troubleshooting Tips">
+<link rel="appendix" href="FunctionIndex.html" title="Appendix D. Function Index">
+<link rel="appendix" href="TypeIndex.html" title="Appendix E. Type Index">
+<link rel="index" href="ConceptIndex.html" title="Index">
+<link rel="section" href="MutexGuide.html#Mutexes" title="Mutexes">
+<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/yahoo/yahoo-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/event/event-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js"></script><script type="text/javascript" src="js/tocnodes.js"></script><script type="text/javascript" src="js/toc.js"></script><script type="text/javascript">
+    document.write("<style> div.toc {display: none} </style>"); 
+  </script>
+</head>
+<body>
+<div class="doctitle">
+<a href="index.html">Home</a>
+<img src="images/docbook/ts75.png"><h1 class="doctitle">Traffic Server Software Developers Kit</h1>
+</div>
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="MIMEHeaders.html">Prev</a> — MIME Headers</div>
+<div class="navnext">Chapter 12. Continuations — <a accesskey="n" href="Continuations.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="MutexGuide"></a>Chapter 11. Mutex Guide</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="MutexGuide.html#Mutexes">Mutexes</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="MutexGuide.html#LockingGlobalData">Locking Global Data</a></span></dt>
+<dt><span class="section"><a href="MutexGuide.html#ProtectContinuationData">Protecting a Continuation’s Data</a></span></dt>
+<dt><span class="section"><a href="MutexGuide.html#AssocContinuationToHTTPTx">How to Associate a Continuation to Every HTTP
+        Transaction</a></span></dt>
+<dt><span class="section"><a href="MutexGuide.html#AddNewContinuation">How to Add the New Continuation</a></span></dt>
+<dt><span class="section"><a href="MutexGuide.html#StoreDataSpecificHTTPTx">How to Store Data Specific to Each HTTP Transaction</a></span></dt>
+<dt><span class="section"><a href="MutexGuide.html#UsingLocks">Using Locks</a></span></dt>
+<dt><span class="section"><a href="MutexGuide.html#ContinuationsCreatedHTTPTx">Special Case: Continuations Created for HTTP
+        Transactions</a></span></dt>
+</dl></dd>
+</dl>
+</div>
+<p>Use mutexes to lock shared data. This chapter explains how to use
+    the mutex interface.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="Mutexes"></a>Mutexes<a class="indexterm" name="id385032"></a></h2></div></div></div>
+<p>A mutex is the basic synchronization<a class="indexterm" name="id385044"></a> method used within Traffic Server to protect data from
+      simultaneous access by multiple threads. A mutex acts as a lock that
+      protects data in one program thread from being accessed by another
+      thread.</p>
+<p><a class="indexterm" name="id385054"></a>The Traffic Server API provides two functions that attempt
+      to access and lock the data: <code class="function">InkMutexLockTry</code> and
+      <code class="function">INKMutexLock</code>. <code class="function">INKMutexLock</code> is
+      a blocking call; if you use it, you can slow Traffic Server performance
+      (transaction processing pauses until the mutex is unlocked). It should
+      be used only on threads created by the plugin
+      (<code class="function">INKContThreadCreate</code>). Never use it on a
+      continuation handler called back by HTTP SM or Cache, Net or Event
+      Processor. Even if the critical section is very small, do not use it. If
+      you need to update a flag, set a variable, use atomic operations. If
+      <code class="function">INKMutexLock</code> is used in any case other than the one
+      recommended above, the result will cause serious performance impact.
+      <code class="function">INKMutexLockTry</code>, on the other hand, attempts to
+      lock the mutex only if it is unlocked (not being used by another
+      thread). It should be used in all cases other than the above mentioned
+      <code class="function">INKMutexLock</code> case. If the
+      <code class="function">INKMutexLockTry</code> attempt fails, you can schedule a
+      future attempt, which must be at least 10 milliseconds later. See for an
+      example.</p>
+<p>Inktomi recommends that, in general, you use
+      <code class="code">INKMutexLockTry</code> rather than
+      <code class="code">INKMutexLock</code>.</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="function">InkMutexLockTry</code> is required if you are
+          tying to lock Traffic Server internal or system resources, such as
+          network, cache, eventProcessor, HTTP state machines and IO
+          buffers.</p></li>
+<li><p><code class="function">InkMutexLockTry</code> is required if you are
+          making any blocking calls, such as network or cache or file IO
+          calls.</p></li>
+<li><p><code class="function">INKMutexLock</code> might not be necessary if
+          you are not making blocking calls, and if you are only accessing
+          local resources.</p></li>
+</ul></div>
+<p>Traffic Server API uses the <code class="function">INKMutex</code> type for
+      a mutex.</p>
+<p>There are two typical uses of mutex. One use is to lock global
+      data or data shared by various continuations. The other typical usage is
+      to lock data associated to a continuation (data that might be accessed
+      by other continuations).</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="LockingGlobalData"></a>Locking Global Data</h3></div></div></div>
+<p>The <code class="filename">blacklist-1.c</code> sample plugin implements
+        an example of this type. The blacklist plugin reads its blacklisted
+        sites from a configuration file. File read operations are protected by
+        a mutex created in <code class="filename">INKPluginInit</code>. The
+        <code class="filename">blacklist-1.c</code> code uses
+        <code class="filename">INKMutexLockTry</code> instead of
+        <code class="filename">InkMutexLock</code>. See <a href="App_SampleSourceCode.html#Sample_blacklist-1.c" title="blacklist-1.c">“blacklist-1.c”</a> for the
+        <code class="filename">blacklist-1.c</code> code (start by looking at the <a href="InitializationFunctions.html#INKPluginInit" title="INKPluginInit"><code class="code">INKPluginInit</code></a> function).
+        The general guideline for locking shared data is:</p>
+<div class="orderedlist"><ol type="1">
+<li><p>Create a mutex for this shared data using <a href="MutexFunctions.html#INKMutexCreate" title="INKMutexCreate"><code class="code">INKMutexCreate</code></a>.</p></li>
+<li><p>Whenever you need to read or modify this data, first lock it
+            by calling <a href="INKMutexLockTry.html" title="INKMutexLockTry"><code class="code">INKMutexLockTry</code></a>.
+            Then read or modify the data.</p></li>
+<li><p>When you are done with the data, unlock it with <a href="INKMutexUnlock.html" title="INKMutexUnlock">INKMutexUnlock</a>. If you are
+            unlocking data accessed during the processing of an HTTP
+            transaction, you must unlock it before calling <a href="HTTPTransactionFunctions.html#INKHttpTxnReenable" title="INKHttpTxnReenable">INKHttpTxnReenable</a>.</p></li>
+</ol></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ProtectContinuationData"></a>Protecting a Continuation’s Data</h3></div></div></div>
+<p>You need to create a mutex to protect a continuation’s data if
+        it might be accessed by other continuations or processes.</p>
+<div class="orderedlist"><ol type="1">
+<li>
+<p>Create a mutex for the continuation using
+            <code class="function">INKMutexCreate</code>. For example,</p>
+<pre class="programlisting">INKMutex mutexp;
+mutexp = INKMutexCreate ();</pre>
+</li>
+<li>
+<p>When you create the continuation, specify this mutex as the
+            continuation’s mutex. For example,</p>
+<pre class="programlisting">INKCont contp;
+contp = INKContCreate (handler, mutexp);</pre>
+</li>
+</ol></div>
+<p>If any other functions want to access contp’s data, it is up to
+        them to get contp’s mutex (using, for example,
+        <code class="function">INKContMutexGet</code>) and lock it. See the sample
+        Protocol plugin for usage.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="AssocContinuationToHTTPTx"></a>How to Associate a Continuation to Every HTTP
+        Transaction</h3></div></div></div>
+<p>There might be several reasons to create a continuation for each
+        HTTP transaction that calls back your plugin. Some examples
+        include:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>register hooks locally with the new continuation instead of
+            registering them globally to the continuation plugin.</p></li>
+<li><p>store data specific to each HTTP transaction that you might
+            need to reuse across various hooks.</p></li>
+<li><p>use of APIs (like <code class="function">INKHostLookup</code>) which
+            will call back this continuation with a certain event.</p></li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="AddNewContinuation"></a>How to Add the New Continuation</h3></div></div></div>
+<p>A typical way of adding the new continuation is to register the
+        plugin continuation to be called back by HTTP transactions globally
+        when they reach <code class="code">INK_HTTP_TXN_START_HOOK</code>. Refer to the
+        example below using a transaction specific continuation called
+        <code class="code">txn_contp</code>.</p>
+<pre class="programlisting">   void INKPluginInit(int argc, const char *argv[]) 
+     { 
+        /* Plugin continuation */ 
+        INKCont contp; 
+        if ((contp = INKContCreate (plugin_cont_handler, NULL)) == INK_ERROR_PTR) { 
+            LOG_ERROR("INKContCreate"); 
+        } else { 
+        if (INKHttpHookAdd (INK_HTTP_TXN_START_HOOK, contp) == INK_ERROR) { 
+LOG_ERROR("INKHttpHookAdd"); 
+} 
+         } 
+     }</pre>
+<p>In the plugin continuation handler, create the new continuation
+        <code class="code">txn_contp</code>, and register it to be called back at
+        <code class="code">INK_HTTP_TXN_CLOSE_HOOK</code>:</p>
+<pre class="programlisting">static int plugin_cont_handler(INKCont contp, INKEvent event, void *edata) 
+     { 
+        INKHttpTxn txnp = (INKHttpTxn)edata; 
+       INKCont txn_contp; 
+
+         switch (event) { 
+         case INK_EVENT_HTTP_TXN_START: 
+             /* Create the HTTP txn continuation */ 
+             txn_contp = INKContCreate(txn_cont_handler, NULL); 
+
+             /* Register txn_contp to be called back when txnp reaches INK_HTTP_TXN_CLOSE_HOOK */ 
+             if (INKHttpTxnHookAdd (txnp, INK_HTTP_TXN_CLOSE_HOOK, txn_contp) == INK_ERROR) { 
+                 LOG_ERROR("INKHttpTxnHookAdd"); 
+             } 
+
+             break; 
+
+         default: 
+             INKAssert(!"Unexpected Event"); 
+             break; 
+         } 
+
+         if (INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE) == INK_ERROR) { 
+             LOG_ERROR("INKHttpTxnReenable"); 
+         } 
+
+         return 0; 
+     }</pre>
+<p>Have the <code class="code">txn_contp</code></p>
+<pre class="programlisting">static int txn_cont_handler(INKCont txn_contp, INKEvent event, void *edata) 
+     { 
+         INKHttpTxn txnp; 
+         switch (event) { 
+         case INK_EVENT_HTTP_TXN_CLOSE: 
+             txnp = (INKHttpTxn) edata; 
+             INKContDestroy(txn_contp); 
+             break; 
+
+         default: 
+             INKAssert(!"Unexpected Event"); 
+             break; 
+         } 
+
+         if (INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE) == INK_ERROR) { 
+             LOG_ERROR("INKHttpTxnReenable"); 
+         } 
+
+         return 0; 
+     }</pre>
+<p> handler destory itself when the HTTP transaction is
+        closed. If you forget, your plugin will have a big memory leak.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="StoreDataSpecificHTTPTx"></a>How to Store Data Specific to Each HTTP Transaction</h3></div></div></div>
+<p>For the example above, store the data in the txn_contp data
+        structure. This means that you will create your own data structure.
+        Suppose you want to store the state of the HTTP transaction:</p>
+<pre class="programlisting">   typedef struct { 
+         int state; 
+     } ContData;</pre>
+<p>You would need to allocate the memory and initialize this
+        structure for each HTTP txnp. You can do that in the plugin
+        continuation handler when it is called back with
+        <code class="code">INK_EVENT_HTTP_TXN_START</code></p>
+<pre class="programlisting">static int plugin_cont_handler(INKCont contp, INKEvent event, void *edata) 
+     { 
+        INKHttpTxn txnp = (INKHttpTxn)edata; 
+       INKCont txn_contp; 
+        ContData *contData; 
+
+         switch (event) { 
+         case INK_EVENT_HTTP_TXN_START: 
+             /* Create the HTTP txn continuation */ 
+             txn_contp = INKContCreate(txn_cont_handler, NULL); 
+
+             /* Allocate and initialize the txn_contp data */ 
+             contData = (ContData*) INKmalloc(sizeof(ContData)); 
+             contData-&gt;state = 0; 
+             if (INKContDataSet(txn_contp, contData) == INK_ERROR) { 
+                 LOG_ERROR("INKContDataSet"); 
+             } 
+
+             /* Register txn_contp to be called back when txnp reaches INK_HTTP_TXN_CLOSE_HOOK */ 
+             if (INKHttpTxnHookAdd (txnp, INK_HTTP_TXN_CLOSE_HOOK, txn_contp) == INK_ERROR) { 
+                 LOG_ERROR("INKHttpTxnHookAdd"); 
+             } 
+
+             break; 
+
+         default: 
+             INKAssert(!"Unexpected Event"); 
+             break; 
+         } 
+
+         if (INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE) == INK_ERROR) { 
+             LOG_ERROR("INKHttpTxnReenable"); 
+         } 
+
+         return 0; 
+     }
+For accessing this data from anywhere, use INKContDataGet:
+INKCont txn_contp; 
+     ContData *contData; 
+
+     contData = INKContDataGet(txn_contp); 
+     if (contData == INK_ERROR_PTR) { 
+         LOG_ERROR("INKContDataGet"); 
+     } 
+     contData-&gt;state = 1;
+Remember to free this memory before destroying the continuation:
+static int txn_cont_handler(INKCont txn_contp, INKEvent event, void *edata) 
+     { 
+         INKHttpTxn txnp; 
+         ContData *contData; 
+         switch (event) { 
+         case INK_EVENT_HTTP_TXN_CLOSE: 
+             txnp = (INKHttpTxn) edata; 
+             contData = INKContDataGet(txn_contp); 
+             if (contData == INK_ERROR_PTR) { 
+                 LOG_ERROR("INKContDataGet"); 
+             } else { 
+                 INKfree(contData); 
+             } 
+             INKContDestroy(txn_contp); 
+             break; 
+
+         default: 
+             INKAssert(!"Unexpected Event"); 
+             break; 
+         } 
+
+         if (INKHttpTxnReenable(txnp, INK_EVENT_HTTP_CONTINUE) == INK_ERROR) { 
+             LOG_ERROR("INKHttpTxnReenable"); 
+         } 
+
+         return 0; 
+     }</pre>
+<p>:</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="UsingLocks"></a>Using Locks</h3></div></div></div>
+<p>You do not need to use locks when a continuation has registered
+        itself to be called back by HTTP hooks and it only uses the HTTP APIs.
+        In the example above, the continuation <code class="code">txn_contp</code> has
+        registered itself to be called back at HTTP hooks, and it only uses
+        the HTTP APIs. In this case only, it is safe to access data shared
+        between <code class="code">txnp</code> and <code class="code">txn_contp</code> without grabbing
+        a lock. In the example above <code class="code">txn_contp</code> is created with a
+        <code class="code">NULL</code> mutex. This works because the HTTP transaction
+        <code class="code">txnp</code> is the only which will call back
+        <code class="code">txn_contp</code>, and you are guaranteed that
+        <code class="code">txn_contp</code> will be called back only one hook at a time.
+        After processing is done <code class="code">txn_contp</code> will reenable
+        <code class="code">txnp</code>.</p>
+<p>In all other cases, you should create a mutex with the
+        continuation. Basically in the case where you are using iocore APIs,
+        or any other API where <code class="code">txn_contp</code> is scheduled to be
+        called back by a processor (the cache processor, the DNS
+        processor...), a lock is needed. This ensures that
+        <code class="code">txn_contp</code> will be called back only one at a time, (i.e.
+        you are sure that <code class="code">txn_contp</code> will not be called back by
+        both <code class="code">txnp</code> and by the cache processor simultaneously,
+        which would result in a situation where you are executing two pieces
+        of code in conflict!)</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ContinuationsCreatedHTTPTx"></a>Special Case: Continuations Created for HTTP
+        Transactions</h3></div></div></div>
+<p>If your plugin creates a new continuation for each HTTP
+        transaction, you probably do not have to create a new mutex for it,
+        because each HTTP transaction (<code class="code">INKHttpTxn</code> object) already
+        has its own mutex.</p>
+<p>For example, if you have code such as the following, it is not
+        necessary to specify a mutex for the continuation created in
+        <code class="code">txn_handler</code>:</p>
+<pre class="programlisting">static void
+txn_handler (INKHttpTxn txnp, INKCont contp) {
+   INKCont newCont;
+   ....
+   newCont = INKContCreate (newCont_handler, NULL);
+   //It's not necessary to create a new mutex for newCont.
+
+   ...
+
+   INKHttpTxnReenable (txnp, INK_EVENT_HTTP_CONTINUE);
+}
+
+static int
+test_plugin (INKCont contp, INKEvent event, void *edata) {
+   INKHttpTxn txnp = (INKHttpTxn) edata;
+
+   switch (event) {
+   case INK_EVENT_HTTP_READ_REQUEST_HDR:
+      txn_handler (txnp, contp);
+      return 0;
+   default:
+      break;
+   }
+   return 0;
+}</pre>
+<p>The mutex functions are:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="MutexFunctions.html#INKMutexCreate" title="INKMutexCreate">“INKMutexCreate”</a></p></li>
+<li><p><a href="INKMutexLock.html" title="INKMutexLock">“INKMutexLock”</a></p></li>
+<li><p><a href="INKMutexLockTry.html" title="INKMutexLockTry">“INKMutexLockTry”</a></p></li>
+</ul></div>
+</div>
+</div>
+</div>
+</body>
+</html>

Propchange: incubator/trafficserver/site/trunk/docs/sdk/MutexGuide.html
------------------------------------------------------------------------------
    svn:keywords = Id

Added: incubator/trafficserver/site/trunk/docs/sdk/NamingConventions.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/NamingConventions.html?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/NamingConventions.html (added)
+++ incubator/trafficserver/site/trunk/docs/sdk/NamingConventions.html Thu Oct 29 23:23:25 2009
@@ -0,0 +1,95 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Naming Conventions</title>
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/reset/reset-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/fonts/fonts-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc-chunk.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="up" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="prev" href="PlusingRegisAndVersionCkg.html" title="Plugin Registration and Version Checking">
+<link rel="next" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="preface" href="Preface.html" title="Preface">
+<link rel="chapter" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="chapter" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="index" href="CreatingTSPlugins.html#id372630" title="Index">
+<link rel="chapter" href="ch03.html" title="Chapter 3. Remap Plugin">
+<link rel="chapter" href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">
+<link rel="chapter" href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">
+<link rel="chapter" href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">
+<link rel="chapter" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="chapter" href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">
+<link rel="chapter" href="MiscellaneousInterfaceGuide.html" title="Chapter 9. Miscellaneous Interface Guide">
+<link rel="chapter" href="HTTPHeaders.html" title="Chapter 10. HTTP Headers">
+<link rel="chapter" href="MutexGuide.html" title="Chapter 11. Mutex Guide">
+<link rel="chapter" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="chapter" href="PluginConfigurations.html" title="Chapter 13. Plugin Configurations">
+<link rel="chapter" href="ActionsGuide.html" title="Chapter 14. Actions Guide">
+<link rel="chapter" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="chapter" href="PluginManagement.html" title="Chapter 16. Plugin Management">
+<link rel="chapter" href="AddingStatistics.html" title="Chapter 17. Adding Statistics">
+<link rel="chapter" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="appendix" href="App_SampleSourceCode.html" title="Appendix A. Sample Source Code">
+<link rel="appendix" href="App_DeprecatedFunctions.html" title="Appendix B. Deprecated Functions">
+<link rel="appendix" href="App_Troubleshooting.html" title="Appendix C. Troubleshooting Tips">
+<link rel="appendix" href="FunctionIndex.html" title="Appendix D. Function Index">
+<link rel="appendix" href="TypeIndex.html" title="Appendix E. Type Index">
+<link rel="index" href="ConceptIndex.html" title="Index">
+<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/yahoo/yahoo-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/event/event-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js"></script><script type="text/javascript" src="js/tocnodes.js"></script><script type="text/javascript" src="js/toc.js"></script><script type="text/javascript">
+    document.write("<style> div.toc {display: none} </style>"); 
+  </script>
+</head>
+<body>
+<div class="doctitle">
+<a href="index.html">Home</a>
+<img src="images/docbook/ts75.png"><h1 class="doctitle">Traffic Server Software Developers Kit</h1>
+</div>
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="PlusingRegisAndVersionCkg.html">Prev</a> — Plugin Registration and Version Checking</div>
+<div class="navnext">Chapter 2. How to Create Traffic Server Plugins — <a accesskey="n" href="CreatingTSPlugins.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="NamingConventions"></a>Naming Conventions</h2></div></div></div>
+<p>The Traffic Server API adheres to the following naming
+      conventions:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>The <code class="filename">INK</code> prefix is used for all function
+          and variable names defined in the Traffic Server API. For example:
+          <code class="filename">INK_EVENT_NONE</code>,<code class="filename">INKMutex</code>
+          and <code class="filename">INKContCreate</code>.</p></li>
+<li><p>Enumerated values are always written in all uppercase letters.
+          Examples: <em class="parameter"><code>INK_EVENT_NONE</code></em> and
+          <em class="parameter"><code>INK_VC_CLOSE_ABORT</code></em>.</p></li>
+<li><p>Constant values are all upper case. Enumerated values can be
+          seen as a subset of constants. Examples:
+          <code class="code"><code class="constant">INK_URL_SCHEME_FILE</code></code> and
+          <code class="code">INK_MIME_FIELD_ACCEPT</code>.</p></li>
+<li><p>The names of defined types are mixed-case. Examples:
+          <em class="parameter"><code>INKHttpSsn</code></em> and
+          <em class="parameter"><code>INKHttpTxn</code></em>.</p></li>
+<li><p>Function names are mixed-case. Examples:
+          <code class="function">INKUrlCreate</code> and
+          <code class="function">INKContDestroy</code>.</p></li>
+<li><p>Function names use the following subject-verb naming style:
+          <code class="code">INK-&lt;subject&gt;-&lt;verb&gt;</code>, where
+          <code class="code">&lt;subject&gt;</code> goes from general to specific. This
+          makes it easier to determine what a function does by reading its
+          name. For example, the function to retrieve the password field (the
+          specific subject) from a URL (the general subject) is
+          <code class="code">INKUrlPasswordGet</code>.</p></li>
+<li><p>Common verbs like <code class="code">Create</code>, <code class="code">Destroy</code>,
+          <code class="code">Get</code>, <code class="code">Set</code>, <code class="code">Copy</code>,
+          <code class="code">Find</code>, <code class="code">Retrieve</code>, <code class="code">Insert</code>,
+          <code class="code">Remove</code> and <code class="code">Delete</code> are used only when
+          appropriate.</p></li>
+</ul></div>
+</div>
+</body>
+</html>

Propchange: incubator/trafficserver/site/trunk/docs/sdk/NamingConventions.html
------------------------------------------------------------------------------
    svn:keywords = Id

Added: incubator/trafficserver/site/trunk/docs/sdk/NetVconnections.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/NetVconnections.html?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/NetVconnections.html (added)
+++ incubator/trafficserver/site/trunk/docs/sdk/NetVconnections.html Thu Oct 29 23:23:25 2009
@@ -0,0 +1,72 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Net Vconnections</title>
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/reset/reset-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/fonts/fonts-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc-chunk.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="up" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="prev" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="next" href="Transformations_IO.html" title="Transformations">
+<link rel="preface" href="Preface.html" title="Preface">
+<link rel="chapter" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="chapter" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="index" href="CreatingTSPlugins.html#id372630" title="Index">
+<link rel="chapter" href="ch03.html" title="Chapter 3. Remap Plugin">
+<link rel="chapter" href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">
+<link rel="chapter" href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">
+<link rel="chapter" href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">
+<link rel="chapter" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="chapter" href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">
+<link rel="chapter" href="MiscellaneousInterfaceGuide.html" title="Chapter 9. Miscellaneous Interface Guide">
+<link rel="chapter" href="HTTPHeaders.html" title="Chapter 10. HTTP Headers">
+<link rel="chapter" href="MutexGuide.html" title="Chapter 11. Mutex Guide">
+<link rel="chapter" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="chapter" href="PluginConfigurations.html" title="Chapter 13. Plugin Configurations">
+<link rel="chapter" href="ActionsGuide.html" title="Chapter 14. Actions Guide">
+<link rel="chapter" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="chapter" href="PluginManagement.html" title="Chapter 16. Plugin Management">
+<link rel="chapter" href="AddingStatistics.html" title="Chapter 17. Adding Statistics">
+<link rel="chapter" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="appendix" href="App_SampleSourceCode.html" title="Appendix A. Sample Source Code">
+<link rel="appendix" href="App_DeprecatedFunctions.html" title="Appendix B. Deprecated Functions">
+<link rel="appendix" href="App_Troubleshooting.html" title="Appendix C. Troubleshooting Tips">
+<link rel="appendix" href="FunctionIndex.html" title="Appendix D. Function Index">
+<link rel="appendix" href="TypeIndex.html" title="Appendix E. Type Index">
+<link rel="index" href="ConceptIndex.html" title="Index">
+<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/yahoo/yahoo-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/event/event-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js"></script><script type="text/javascript" src="js/tocnodes.js"></script><script type="text/javascript" src="js/toc.js"></script><script type="text/javascript">
+    document.write("<style> div.toc {display: none} </style>"); 
+  </script>
+</head>
+<body>
+<div class="doctitle">
+<a href="index.html">Home</a>
+<img src="images/docbook/ts75.png"><h1 class="doctitle">Traffic Server Software Developers Kit</h1>
+</div>
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="IOGuide.html">Prev</a> — Chapter 15. IO Guide</div>
+<div class="navnext">Transformations — <a accesskey="n" href="Transformations_IO.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="NetVconnections"></a>Net Vconnections</h2></div></div></div>
+<p>A network vconnection (netvconnection) is a wrapper around a TCP
+      socket that allows the socket to work within the Traffic Server
+      vconnection framework. See <a href="IOGuide.html#Vconnections" title="Vconnections">“Vconnections”</a> for more
+      information about the Traffic Server abstraction for doing asynchronous
+      IO.</p>
+<p>The net vconnection functions are:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="NetvconnectionFunctions.html#INKNetAccept" title="INKNetAccept">“INKNetAccept”</a></p></li>
+<li><p><a href="INKNetConnect.html" title="INKNetConnect">“INKNetConnect”</a></p></li>
+</ul></div>
+</div>
+</body>
+</html>

Propchange: incubator/trafficserver/site/trunk/docs/sdk/NetVconnections.html
------------------------------------------------------------------------------
    svn:keywords = Id

Added: incubator/trafficserver/site/trunk/docs/sdk/NetvconnectionFunctions.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/NetvconnectionFunctions.html?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/NetvconnectionFunctions.html (added)
+++ incubator/trafficserver/site/trunk/docs/sdk/NetvconnectionFunctions.html Thu Oct 29 23:23:25 2009
@@ -0,0 +1,116 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Netvconnection Functions</title>
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/reset/reset-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/fonts/fonts-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc-chunk.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="up" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="prev" href="INKVConnWriteVIOGet.html" title="INKVConnWriteVIOGet">
+<link rel="next" href="INKNetConnect.html" title="INKNetConnect">
+<link rel="preface" href="Preface.html" title="Preface">
+<link rel="chapter" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="chapter" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="index" href="CreatingTSPlugins.html#id372630" title="Index">
+<link rel="chapter" href="ch03.html" title="Chapter 3. Remap Plugin">
+<link rel="chapter" href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">
+<link rel="chapter" href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">
+<link rel="chapter" href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">
+<link rel="chapter" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="chapter" href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">
+<link rel="chapter" href="MiscellaneousInterfaceGuide.html" title="Chapter 9. Miscellaneous Interface Guide">
+<link rel="chapter" href="HTTPHeaders.html" title="Chapter 10. HTTP Headers">
+<link rel="chapter" href="MutexGuide.html" title="Chapter 11. Mutex Guide">
+<link rel="chapter" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="chapter" href="PluginConfigurations.html" title="Chapter 13. Plugin Configurations">
+<link rel="chapter" href="ActionsGuide.html" title="Chapter 14. Actions Guide">
+<link rel="chapter" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="chapter" href="PluginManagement.html" title="Chapter 16. Plugin Management">
+<link rel="chapter" href="AddingStatistics.html" title="Chapter 17. Adding Statistics">
+<link rel="chapter" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="appendix" href="App_SampleSourceCode.html" title="Appendix A. Sample Source Code">
+<link rel="appendix" href="App_DeprecatedFunctions.html" title="Appendix B. Deprecated Functions">
+<link rel="appendix" href="App_Troubleshooting.html" title="Appendix C. Troubleshooting Tips">
+<link rel="appendix" href="FunctionIndex.html" title="Appendix D. Function Index">
+<link rel="appendix" href="TypeIndex.html" title="Appendix E. Type Index">
+<link rel="index" href="ConceptIndex.html" title="Index">
+<link rel="subsection" href="NetvconnectionFunctions.html#INKNetAccept" title="INKNetAccept">
+<link rel="subsection" href="INKNetConnect.html" title="INKNetConnect">
+<link rel="subsection" href="INKNetVConnRemoteIPGet.html" title="INKNetVConnRemoteIPGet">
+<link rel="subsection" href="INKNetVConnRemotePortGet.html" title="INKNetVConnRemotePortGet">
+<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/yahoo/yahoo-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/event/event-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js"></script><script type="text/javascript" src="js/tocnodes.js"></script><script type="text/javascript" src="js/toc.js"></script><script type="text/javascript">
+    document.write("<style> div.toc {display: none} </style>"); 
+  </script>
+</head>
+<body>
+<div class="doctitle">
+<a href="index.html">Home</a>
+<img src="images/docbook/ts75.png"><h1 class="doctitle">Traffic Server Software Developers Kit</h1>
+</div>
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKVConnWriteVIOGet.html">Prev</a> — INKVConnWriteVIOGet</div>
+<div class="navnext">INKNetConnect — <a accesskey="n" href="INKNetConnect.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="NetvconnectionFunctions"></a>Netvconnection Functions</h2></div></div></div>
+<p></p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKNetAccept"></a>INKNetAccept</h3></div></div></div>
+<p>Accepts a TCP/IP connection on a specified port.</p>
+<div class="variablelist"><dl>
+<dt><span class="term">Prototype</span></dt>
+<dd><p><code class="code">INKAction INKNetAccept (INKCont
+              <em class="replaceable"><code>contp</code></em>, int
+              <em class="replaceable"><code>port</code></em>)</code></p></dd>
+<dt><span class="term">Arguments</span></dt>
+<dd>
+<p><code class="function">INKCont</code>
+              <code class="code"><em class="replaceable"><code>contp</code></em></code> is the
+              continuation that is called back when a connection is
+              accepted.</p>
+<p><code class="code">int
+              </code><code class="code"><em class="replaceable"><code>port</code></em></code> is the port
+              to listen to for incoming TCP/IP connections.</p>
+</dd>
+<dt><span class="term">Description</span></dt>
+<dd>
+<p>Accepts a TCP/IP connection on
+              <code class="code"><em class="replaceable"><code>port</code></em></code>. When Traffic
+              Server receives a connection on a specified port, it calls back
+              <code class="code"><em class="replaceable"><code>contp</code></em></code> with the event
+              <code class="code">INK_EVENT_NET_ACCEPT</code> or
+              <code class="code">INK_EVENT_NET_ACCEPT_FAILED</code></p>
+<p>If event is <code class="code">INK_EVENT_NET_ACCEPT</code>, the
+              <code class="code">void * </code><code class="code"><em class="replaceable"><code>data</code></em></code>
+              passed to the handler of the continuation
+              <code class="code"><em class="replaceable"><code>contp</code></em></code> is a data of type
+              NetVConnection representing the connection.</p>
+<p>If event is <code class="code">INK_EVENT_NET_ACCEPT_FAILED</code>, it
+              means an attempt of connection was aborted or failed. The plugin
+              should just return from the continuation's handler.</p>
+<p>The user (<code class="code"><em class="replaceable"><code>contp</code></em></code>)
+              has the option to cancel the action returned by INKNetAccept by
+              using <code class="function">INKActionCancel</code>.</p>
+</dd>
+<dt><span class="term">Returns</span></dt>
+<dd>
+<p>An INKAction object if successful.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an argument was incorrect or
+              if the API failed.</p>
+</dd>
+<dt><span class="term">First Release</span></dt>
+<dd><p>Traffic Server 5.2</p></dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>

Propchange: incubator/trafficserver/site/trunk/docs/sdk/NetvconnectionFunctions.html
------------------------------------------------------------------------------
    svn:keywords = Id

Added: incubator/trafficserver/site/trunk/docs/sdk/NewProtocolPlugins.html
URL: http://svn.apache.org/viewvc/incubator/trafficserver/site/trunk/docs/sdk/NewProtocolPlugins.html?rev=831152&view=auto
==============================================================================
--- incubator/trafficserver/site/trunk/docs/sdk/NewProtocolPlugins.html (added)
+++ incubator/trafficserver/site/trunk/docs/sdk/NewProtocolPlugins.html Thu Oct 29 23:23:25 2009
@@ -0,0 +1,404 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>Chapter 6. New Protocol Plugins</title>
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/reset/reset-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/fonts/fonts-min.css" type="text/css">
+<link rel="stylesheet" href="http://yui.yahooapis.com/2.2.2/build/treeview/assets/tree.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc.css" type="text/css">
+<link rel="stylesheet" href="css/ydoc-chunk.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.69.1">
+<link rel="start" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="up" href="index.html" title="Traffic Server Software Developers Kit">
+<link rel="prev" href="SampleBufferedNullTransformPlugin.html" title="The Sample Buffered Null Transform Plugin">
+<link rel="next" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="preface" href="Preface.html" title="Preface">
+<link rel="chapter" href="GetingStarted.html" title="Chapter 1. Getting Started">
+<link rel="chapter" href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">
+<link rel="index" href="CreatingTSPlugins.html#id372630" title="Index">
+<link rel="chapter" href="ch03.html" title="Chapter 3. Remap Plugin">
+<link rel="chapter" href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">
+<link rel="chapter" href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">
+<link rel="chapter" href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">
+<link rel="chapter" href="ch07.html" title="Chapter 7. Cache Plugin">
+<link rel="chapter" href="HTTPHooksAndTransactions.html" title="Chapter 8. HTTP Hooks and Transactions">
+<link rel="chapter" href="MiscellaneousInterfaceGuide.html" title="Chapter 9. Miscellaneous Interface Guide">
+<link rel="chapter" href="HTTPHeaders.html" title="Chapter 10. HTTP Headers">
+<link rel="chapter" href="MutexGuide.html" title="Chapter 11. Mutex Guide">
+<link rel="chapter" href="Continuations.html" title="Chapter 12. Continuations">
+<link rel="chapter" href="PluginConfigurations.html" title="Chapter 13. Plugin Configurations">
+<link rel="chapter" href="ActionsGuide.html" title="Chapter 14. Actions Guide">
+<link rel="chapter" href="IOGuide.html" title="Chapter 15. IO Guide">
+<link rel="chapter" href="PluginManagement.html" title="Chapter 16. Plugin Management">
+<link rel="chapter" href="AddingStatistics.html" title="Chapter 17. Adding Statistics">
+<link rel="chapter" href="FunctionReference.html" title="Chapter 18. Function Reference">
+<link rel="appendix" href="App_SampleSourceCode.html" title="Appendix A. Sample Source Code">
+<link rel="appendix" href="App_DeprecatedFunctions.html" title="Appendix B. Deprecated Functions">
+<link rel="appendix" href="App_Troubleshooting.html" title="Appendix C. Troubleshooting Tips">
+<link rel="appendix" href="FunctionIndex.html" title="Appendix D. Function Index">
+<link rel="appendix" href="TypeIndex.html" title="Appendix E. Type Index">
+<link rel="index" href="ConceptIndex.html" title="Index">
+<link rel="section" href="NewProtocolPlugins.html#AboutSampleProtocol" title="About the Sample Protocol">
+<script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/yahoo/yahoo-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/event/event-min.js"></script><script type="text/javascript" src="http://yui.yahooapis.com/2.2.2/build/treeview/treeview-min.js"></script><script type="text/javascript" src="js/tocnodes.js"></script><script type="text/javascript" src="js/toc.js"></script><script type="text/javascript">
+    document.write("<style> div.toc {display: none} </style>"); 
+  </script>
+</head>
+<body>
+<div class="doctitle">
+<a href="index.html">Home</a>
+<img src="images/docbook/ts75.png"><h1 class="doctitle">Traffic Server Software Developers Kit</h1>
+</div>
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="SampleBufferedNullTransformPlugin.html">Prev</a> — The Sample Buffered Null Transform Plugin</div>
+<div class="navnext">Chapter 7. Cache Plugin — <a accesskey="n" href="ch07.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="NewProtocolPlugins"></a>Chapter 6. New Protocol Plugins</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="NewProtocolPlugins.html#AboutSampleProtocol">About the Sample Protocol</a></span></dt>
+<dd><dl>
+<dt><span class="section"><a href="NewProtocolPlugins.html#ProtocolPluginStructure">Protocol Plugin Structure</a></span></dt>
+<dt><span class="section"><a href="NewProtocolPlugins.html#ContinuationsInProtocolPlugin">Continuations in the Protocol Plugin</a></span></dt>
+<dt><span class="section"><a href="NewProtocolPlugins.html#EventFlow">Event Flow</a></span></dt>
+<dt><span class="section"><a href="NewProtocolPlugins.html#ImplementTransStMachine">One Way to Implement a Transaction State Machine</a></span></dt>
+<dt><span class="section"><a href="NewProtocolPlugins.html#ProcTypicalTransaction">Processing a Typical Transaction</a></span></dt>
+</dl></dd>
+</dl>
+</div>
+<p>The new protocol APIs allow you to extend Traffic Server to be a web
+    proxy for any protocol. This chapter describes the new protocol APIs and
+    plugins that support new protocols. It goes through sample Protocol plugin
+    code in detail. The sample Protocol plugin supports a very simple
+    artificial HTTP-like protocol.</p>
+<p>This chapter contains the following sections:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+<p><a href="NewProtocolPlugins.html#AboutSampleProtocol" title="About the Sample Protocol">“About the Sample Protocol”</a></p>
+<p>Gives the state diagram and header structure of the artificial
+        protocol. Describes what the supporting plugin has to do.</p>
+</li>
+<li>
+<p><a href="NewProtocolPlugins.html#ProtocolPluginStructure" title="Protocol Plugin Structure">“Protocol Plugin Structure”</a></p>
+<p>In depth explanation of the Protocol plugin. Starts with overall
+        architecture, and describes how to write continuations as state
+        machines. Ends with a walk-through of the Protocol plugin code as it
+        processes a transaction.</p>
+</li>
+</ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title" style="clear: both">
+<a name="AboutSampleProtocol"></a>About the Sample Protocol</h2></div></div></div>
+<p>The sample protocol allows a client to ask a server for a file.
+      Clients send requests to a specific Traffic Server port (specified in
+      plugin.config). The requests look like the following:</p>
+<p><span><strong class="command">server_name file_name\n\n</strong></span></p>
+<p>With the Protocol plugin, Traffic Server can accept these
+      requests, parse them, and act as a proxy cache (requesting the file from
+      the origin server on the client’s behalf, and storing copies of the
+      response messages in the cache) The Protocol plugin is a state machine
+      that flows through the states illustrated in <a href="NewProtocolPlugins.html#Fig_SampleProtocolStDiag" title="Figure 6.1. Sample Protocol State Diagram">Figure 6.1, “Sample Protocol State Diagram”</a>. The figure shows the steps that
+      Traffic Server and the Protocol plugin go through to support the sample
+      protocol. In words, Traffic Server and the Protocol plugin must:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>listen for and accept client connections (on the accept port
+          specified in plugin.config)</p></li>
+<li><p>read incoming client requests</p></li>
+<li><p>look up the requested content in the Traffic Server
+          cache</p></li>
+<li><p>serve the content from the cache if the request is a cache hit
+          (this simple example does not do freshness checking)</p></li>
+<li><p>open a connection to the origin server if the request is a
+          cache miss (on the server port specified in plugin.config)</p></li>
+<li><p>forward the request to the origin server</p></li>
+<li><p>receive the origin server response</p></li>
+<li><p>cache the response and send it on to the client</p></li>
+</ul></div>
+<div class="figure">
+<a name="Fig_SampleProtocolStDiag"></a><p class="title"><b>Figure 6.1. Sample Protocol State Diagram</b></p>
+<div class="mediaobject"><img src="images/Protocol_state_diagram.jpg" alt="Sample Protocol State Diagram"></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ProtocolPluginStructure"></a>Protocol Plugin Structure</h3></div></div></div>
+<p>To see how the Protocol plugin works, you need to understand a
+        couple of big pictures. This section assumes you are familiar with the
+        concepts of continuation, Traffic Server’s asynchronous event model,
+        and basic Traffic Server plugin structure. If not, see <a href="GetingStarted.html#GettingStarted">Chapter 1, <i>Getting Started</i></a> and <a href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">Chapter 2, <i>How to Create Traffic Server Plugins</i></a>.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ContinuationsInProtocolPlugin"></a>Continuations in the Protocol Plugin</h3></div></div></div>
+<p>The Protocol plugin creates a static continuation that is an
+        “accept” state machine, a state machine whose job is to accept client
+        connections on the appropriate port. When Traffic Server accepts a net
+        connection from a client on that port, the accept state machine is
+        activated and it creates a new continuation, a transaction state
+        machine. The accept state machine creates one transaction state
+        machine for each transaction (a transaction consists of a client
+        request and Traffic Server’s response). Each transaction state machine
+        lives until the transaction completes, and then it is destroyed. If
+        the client’s request for content is a cache miss, a transaction state
+        machine might have to open a connection to the origin server. This is
+        illustrated in <a href="NewProtocolPlugins.html#Fig_ProtocolPluginOverview" title="Figure 6.2. Protocol Plugin Overview"><a href="NewProtocolPlugins.html#Fig_ProtocolPluginOverview" title="Figure 6.2. Protocol Plugin Overview">Figure 6.2, “Protocol Plugin Overview”</a></a>.</p>
+<div class="figure">
+<a name="Fig_ProtocolPluginOverview"></a><p class="title"><b>Figure 6.2. Protocol Plugin Overview</b></p>
+<div class="mediaobject"><img src="images/protocol_sm_big.jpg" alt="Protocol Plugin Overview"></div>
+</div>
+<p>Now you can see the first steps in writing this Protocol plugin:
+        in INKPluginInit, you must create a continuation that listens for net
+        connections on the client port specified in
+        <code class="filename">plugin.config</code> (this continuation is the accept
+        state machine).</p>
+<p>Here is a summary of the continuations implemented for the
+        Protocol plugin:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>An accept state machine that listens for client connections,
+            and creates transaction state machines whenever Traffic Server
+            accepts a new client connection. The accept state machine lives as
+            long as Traffic Server is running.</p></li>
+<li><p>Transaction state machines that read client requests,
+            process them, and are destroyed when the transaction is
+            done.</p></li>
+</ul></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="EventFlow"></a>Event Flow</h3></div></div></div>
+<p>To understand how to implement the rest of the Protocol plugin
+        you need to understand the flow of events that takes place in the
+        course of a transaction. Unlike HTTP transaction plugins, this plugin
+        must read data from network connections and read and write data to the
+        Traffic Server cache. This means that its continuations do not receive
+        HTTP state machine events; they receive events from Traffic Server’s
+        processor subsystems.</p>
+<p>For example, the accept state machine is activated by an
+        <code class="code">INK_EVENT_NET_ACCEPT</code> event from Traffic Server’s Net
+        Processor. The handler function for the accept state machine must be
+        able to handle that event.</p>
+<p>The transaction state machines are activated when the client
+        connection receives incoming request data. The Net Processor notifies
+        the transaction state machine of incoming data. The transaction state
+        machine reads the data, and then when it is done, initiates a cache
+        lookup of the requested file. When the cache lookup completes, the
+        transaction state machine is activated by the Traffic Server Cache
+        Processor.</p>
+<p>If the transaction state machine has to open a connection to the
+        origin server to fetch content (in the case of a cache miss), the
+        transaction state machine initiates a DNS lookup of the server name.
+        The transaction state machine is activated by a DNS lookup event from
+        the Traffic Server Host Database Processor.</p>
+<p>If the transaction has to connect to the origin server, the
+        transaction state machine initiates a net connection and waits for an
+        event from Net Processor.</p>
+<div class="figure">
+<a name="Fig_ProtocolPluginFlow"></a><p class="title"><b>Figure 6.3. Protocol Plugin Flow of Events</b></p>
+<div class="mediaobject"><img src="images/protocol_evt.jpg" alt="Protocol Plugin Flow of Events"></div>
+</div>
+<p>The flow of events is illustrated in <a href="NewProtocolPlugins.html#Fig_ProtocolPluginFlow" title="Figure 6.3. Protocol Plugin Flow of Events">Figure 6.3, “Protocol Plugin Flow of Events”</a>. The thin straight lines show Net
+        Processor event flow, the thin dashed lines are Host DB event flow,
+        and the thick dashed lines are Cache event flow.</p>
+<p>Notice that this flow of events is independent of the design of
+        the Protocol plugin (whether you build “accept” and “transaction”
+        state machines or not). Any plugin that supports network connections
+        uses the net vconnection interfaces (<code class="code">INKNetAccept</code>,
+        <code class="code">INKNetConnect</code>) and thus receives events from Net
+        Processor. Any plugin that performs cache lookups or cache writes uses
+        <code class="code">INKCacheRead</code>, <code class="code">INKCacheWrite</code>,
+        <code class="code">INKVConnRead</code>, and <code class="code">INKVConnWrite</code> and thus
+        receives events from Cache Processor and the Traffic Server event
+        system; similarly, any plugin that does DNS lookups receives events
+        from the Host DB Processor.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ImplementTransStMachine"></a>One Way to Implement a Transaction State Machine</h3></div></div></div>
+<p>The transaction state machines (TSMs) in the Protocol plugin
+        have to do several things:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>Keep track of the state of the transaction</p></li>
+<li><p>Handle the events they receive (based on the state of the
+            transaction and the event received)</p></li>
+<li><p>Update the state of the transaction as it changes</p></li>
+</ul></div>
+<p>Here is one way you can implement TSMs (details on how the
+        Protocol plugin does this follow in the next section):</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>Create a data structure for transactions that contains all
+            of the state data you need to keep track of. In the Protocol
+            plugin this is a struct, <code class="filename">Txn_SM</code>.</p></li>
+<li><p>When you create the TSM’s continuation, initialize data of
+            type <code class="filename">Txn_SM</code>. Initialize the data to the
+            initial state of a transaction (in this case, a net connection has
+            just been accepted). Associate this data to the TSM continuation
+            using <code class="code">INKContDataSet</code>.</p></li>
+<li><p>Write state handler functions that handle the expected
+            events for each state.</p></li>
+<li><p>Write the handler for the TSM. Its job is to receive events,
+            examine the current state, and execute the appropriate state
+            handler function. In the Protocol plugin, the handler is
+            <code class="code">main_handler</code>. <code class="code">main_handler</code> calls the
+            state handler functions to handle each state.</p></li>
+</ul></div>
+<p>The flow of execution is illustrated in <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+          Protocol Plugin">Figure 6.4, “How Transaction State Machines are Implemented in the
+          Protocol Plugin”</a>.</p>
+<div class="orderedlist"><ol type="1">
+<li><p>The handler for the TSM, (called <code class="code">main_handler</code>
+            in the Protocol plugin) receives the TSM’s events.</p></li>
+<li><p><code class="code">main_handler</code> examines the state of the
+            transaction—in particular, it examines the current handler.</p></li>
+<li><p><code class="code">main_handler</code> calls the
+            <code class="code">current_handler</code>, which is one of the state handler
+            functions, and passes <code class="code">current_handler</code> the current
+            event. In <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+          Protocol Plugin">Figure 6.4, “How Transaction State Machines are Implemented in the
+          Protocol Plugin”</a>, the
+            current handler is <code class="code">state2_handler</code>.</p></li>
+<li><p>The <code class="code">current_handler</code> handles the event, and
+            updates the data. In <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+          Protocol Plugin">Figure 6.4, “How Transaction State Machines are Implemented in the
+          Protocol Plugin”</a>, the state is changed
+            from <code class="code">state2</code> to <code class="code">state3</code> (and the current
+            handler is changed from <code class="code">state2_handler</code> to
+            <code class="code">state3_handler</code>). The next time
+            <code class="code">main_handler</code> receives an event, it will be processed
+            by <code class="code">state3_handler</code>.</p></li>
+<li><p><code class="code">state2_handler</code> arranges the next callback of
+            the TSM. Typically, it gives Traffic Server additional work to do
+            (such as writing a file to cache), in order to progress to the
+            next state. The TSM (<code class="code">main_handler</code>) then waits for the
+            next event to arrive from Traffic Server.</p></li>
+</ol></div>
+<p>This implementation is diagrammed in <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+          Protocol Plugin">Figure 6.4, “How Transaction State Machines are Implemented in the
+          Protocol Plugin”</a>. The details are provided in
+        the next section, a walk through the processing of a typical
+        transaction.</p>
+<div class="figure">
+<a name="Fig_ImplementTransStMachine"></a><p class="title"><b>Figure 6.4. How Transaction State Machines are Implemented in the
+          Protocol Plugin</b></p>
+<div class="mediaobject"><img src="images/txn_sm.jpg" alt="How Transaction State Machines are Implemented in the Protocol Plugin"></div>
+</div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="ProcTypicalTransaction"></a>Processing a Typical Transaction</h3></div></div></div>
+<p>The code is contained in the following files:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="filename">Protocol.c</code> and
+            <code class="filename">Protocol.h</code></p></li>
+<li><p><code class="filename">Accept.c</code> and
+            <code class="filename">Accept.h</code></p></li>
+<li><p><code class="filename">TxnSM.c</code> and
+            <code class="filename">TxnSM.h</code></p></li>
+</ul></div>
+<p>Here is a step-by-step run-through of the code.</p>
+<div class="orderedlist"><ol type="1">
+<li><p>The <code class="function">INKPluginInit</code> function is in
+            <code class="filename">Protocol.c</code>. It checks the validity of the
+            plugin.config entries (there must be two, a client accept port and
+            a server port), and runs an initialization routine,
+            <code class="function">init</code>.</p></li>
+<li><p>The <code class="function">init</code> function (in
+            <code class="filename">Protocol.c</code>) creates the plugin’s log file
+            using <code class="code">INKTextLogObjectCreate</code>.</p></li>
+<li><p>The <code class="function">init</code> function creates the accept
+            state machine using <code class="code">AcceptCreate</code>. The code for
+            <code class="code">AcceptCreate</code> is in
+            <code class="filename">Accept.c</code>.</p></li>
+<li><p>The accept state machine, like the transaction state
+            machine, keeps track of its state via a data structure. This data
+            structure, Accept, is defined in <code class="filename">Accept.h</code>. In
+            <code class="code">AcceptCreate</code>, state data is associated to the new
+            accept state machine using <code class="code">INKContDataSet</code>.</p></li>
+<li><p>The <code class="function">init</code> function arranges the callback
+            of the accept state machine when there is a network connection
+            using <code class="code">INKNetAccept</code>.</p></li>
+<li><p>The handler for the accept state machine is
+            <code class="function">accept_event</code> in
+            <code class="filename">Accept.c</code>. When Traffic Server’s Net Processor
+            sends <code class="code">INK_EVENT_NET_ACCEPT</code> to the accept state
+            machine, <code class="function">accept_event</code> creates a transaction
+            state machine, <code class="code">txn_sm</code>, by calling
+            <code class="code">TxnSMCreate</code>. Notice that
+            <code class="function">accept_event</code> creates a mutex for the
+            transaction state machine; each transaction state machine has its
+            own mutex.</p></li>
+<li><p>The <code class="function">TxnSMCreate</code> function is in
+            <code class="filename">TxnSM.c</code>. The first thing it does is to
+            initialize the transaction’s data. This data is of type
+            <code class="code">TxnSM</code> (defined in <code class="filename">TxnSM.h</code>).
+            Notice that the current handler (<code class="code">q_current_handler</code>)
+            is set to <code class="code">state_start</code>.</p></li>
+<li><p>Then <code class="function">TxnSMCreate</code> creates a transaction
+            state machine using <code class="code">INKContCreate</code>. The handler for
+            the transaction state machine is <code class="code">main_handler</code>.</p></li>
+<li><p><code class="function">main_handler</code> is in
+            <code class="filename">TxnSM.c</code>. When
+            <code class="function">accept_event</code> receives
+            <code class="code">INK_EVENT_NET_ACCEPT</code>, it calls the transaction state
+            machine (<code class="code">INKContCall</code> (<code class="code">txn_sm, 0,
+            NULL);</code>). The event passed to
+            <code class="function">main_handler</code> is 0
+            (<code class="code">INK_EVENT_NONE</code>).</p></li>
+<li><p>The first thing <code class="function">main_handler</code> does is
+            examine the current <code class="code">txn_sm</code> state by calling
+            <code class="code">INKContDataGet</code>. The state is
+            <code class="code">state_start</code>.</p></li>
+<li><p><code class="code">main_handler</code> invokes the handler for
+            state_start by using the function pointer
+            <code class="function">TxnSMHandler</code> (defined in
+            <code class="filename">TxnSM.h</code>).</p></li>
+<li><p>The <code class="function">state_start</code> handler function (in
+            <code class="filename">TxnSM.c</code>) is handed an event (at this stage,
+            the event is <code class="code">INK_EVENT_NET_ACCEPT</code>) and a client
+            vconnection. <code class="function">state_start</code> checks to see if
+            this client vconnection is closed; if not,
+            <code class="function">state_start</code> attempts to read data from the
+            client vconnection into an <code class="code">INKIOBuffer</code>.
+            (<code class="function">state_start</code> is handling the event it
+            receives).</p></li>
+<li><p><code class="function">state_start</code> changes the current handler
+            to <code class="function">state_interface_with_client</code>. (Updates the
+            state of the transaction to the next state).</p></li>
+<li><p><code class="function">state_start</code> initiates a read of the
+            client vconnection (arranges for Traffic Server to send
+            <code class="code">INK_EVENT_VCONN_READ_READY</code> events to the TSM), by
+            calling <code class="code">INKVConnRead</code>.</p></li>
+<li><p><code class="function">state_interface_with_client</code> is
+            activated by the next event from Traffic Server. It checks for
+            errors, and examines the read VIO for the read operation initiated
+            by <code class="code">INKVConnRead</code>.</p></li>
+<li><p>If the read VIO is the <code class="code">client_read_VIO</code> (which
+            we are expecting at this stage in the transaction),
+            <code class="function">state_interface_with_client</code> updates the state
+            to <code class="function">state_read_request_from_client</code></p></li>
+<li><p><code class="function">state_read_request_from_client</code> handles
+            actual <code class="code">INK_EVENT_READ_READY</code> events and reads the
+            client request.</p></li>
+<li><p><code class="function">state_read_request_from_client</code> parses
+            the client request.</p></li>
+<li><p><code class="function">state_read_request_from_client</code> updates
+            the state to the next state,
+            <code class="function">state_handle_cache_lookup</code>.</p></li>
+<li><p><code class="function">state_read_request_from_client</code> arranges
+            for Traffic Server to call back the TSM with the next set of
+            events , initiating the cache lookup, by calling
+            <code class="code">INKCacheRead</code>.</p></li>
+<li><p>When the <code class="code">INKCacheRead</code> sends the TSM
+            <code class="code">INK_EVENT_OPEN_READ</code> (a cache hit) or
+            <code class="code">INK_EVENT_OPEN_READ_FAILED</code> (a cache miss),
+            <code class="function">main_handler</code> calls
+            <code class="function">state_handle_cache_lookup</code>.</p></li>
+</ol></div>
+</div>
+</div>
+</div>
+</body>
+</html>

Propchange: incubator/trafficserver/site/trunk/docs/sdk/NewProtocolPlugins.html
------------------------------------------------------------------------------
    svn:keywords = Id