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->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->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-<subject>-<verb></code>, where
+ <code class="code"><subject></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