You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by bu...@apache.org on 2013/12/24 19:32:22 UTC
svn commit: r891679 [20/24] - in /websites/staging/trafficserver/trunk:
cgi-bin/ content/ content/docs/ content/docs/trunk/
content/docs/trunk/admin/ content/docs/trunk/admin/cluster-howto/
content/docs/trunk/admin/configuration-files/ content/docs/tru...
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MimeHeadersFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MiscellaneousInterfaceGuide.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/MiscellaneousInterfaceGuide.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/MiscellaneousInterfaceGuide.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,56 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 9. Miscellaneous Interface Guide</title>
+<!--#include file="top.html" -->
+<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>
+<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. They are categorized as follows:</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>The C library already provides functions such as
+ <code class="function">printf</code>, <code class="function">malloc</code>, and
+ <code class="function">fopen</code> to perform these tasks. The Traffic Server
+ API versions, however, 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">
+<a name="Interface_Debugging"></a>Debugging Functions</h2></div></div></div>
+<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> checks to see if a debug tag
+ is set. If the debug tag is set, then Traffic Server prints out all debug
+ statements associated with the 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> enables the use of assertion in a
+ plugin.</p></li>
+<li>
+ <p><a href="INKReleaseAssert.html" title="INKReleaseAssert">INKReleaseAssert</a> enables the use of
+ assertion in a plugin.</p></li>
+</ul></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MiscellaneousInterfaceGuide.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,44 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Mutex Functions</title>
+<!--#include file="top.html" -->
+<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">
+<a name="MutexFunctions"></a>Mutex Functions</h2></div></div></div>
+
+
+<ul><b>
+<li><a href="MutexFunctions.html#INKMutexCreate">INKMutexCreate</a></li>
+<li><a href="INKMutexLock.html">INKMutexLock</a></li>
+<li><a href="INKMutexLockTry.html">INKMutexLockTry</a></li>
+<li><a href="INKMutexUnlock.html">INKMutexUnlock</a></li>
+</b>
+</ul>
+
+<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"><b>Prototype</b></span></dt>
+<dd><p><code class="code">INKMutex INKMutexCreate (void)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd><p>Creates a new <code>INKMutex</code>.</p></dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>A handle to the newly-created mutex.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an error occurs.</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexGuide.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexGuide.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexGuide.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,380 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 11. Mutex Guide</title>
+<!--#include file="top.html" -->
+<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>
+<p>Mutexes are used to lock shared data. This chapter explains how to use
+ the mutex interface.</p>
+<ul>
+<li><a href="MutexGuide.html#Mutexes"><b>Mutexes</b></a></li>
+
+<li><b><a href="MutexGuide.html#LockingGlobalData">Locking Global Data</a></span></dt>
+</b>
+<li><b><a href="MutexGuide.html#ProtectContinuationData">Protecting a Continuation's Data</a></b></li>
+<li><b><a href="MutexGuide.html#AssocContinuationToHTTPTx">How to Associate a Continuation With Every HTTP
+ Transaction</a></b></li>
+<li><b><a href="MutexGuide.html#AddNewContinuation">How to Add the New Continuation</a></b></li>
+<li><b><a href="MutexGuide.html#StoreDataSpecificHTTPTx">How to Store Data Specific to Each HTTP Transaction</a></b></li>
+<li><b><a href="MutexGuide.html#UsingLocks">Using Locks</a></b></li>
+<li><b><a href="MutexGuide.html#ContinuationsCreatedHTTPTx">Special Case: Continuations Created for HTTP
+ Transactions</a></b></li>
+</ul>
+
+
+ </div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Mutexes"></a>Mutexes<a class="indexterm" name="id385032"></a></h2></div></div></div>
+<p>A <b>mutex</b> 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"><b>INKMutexLock</b></code> is
+ a blocking call - if you use it, you can slow Traffic Server performance
+ because 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 the Cache, Net, or Event
+ Processor. Even if the critical section is very small, do not use it. If
+ you need to update a flag, then set a variable and/or use atomic operations. If
+ <code class="function">INKMutexLock</code> is used in any case other than the one
+ recommended above, then the result will be a serious performance impact. </p>
+<p><code class="function"><b>INKMutexLockTry</b></code>, on the other hand, attempts to
+ lock the mutex only if it is unlocked (i.e., 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, then you can schedule a
+ future attempt (which must be at least 10 milliseconds later). </p>
+<p>In general, you should use
+ <code class="code">INKMutexLockTry</code> instead of
+ <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
+ the network, cache, event processor, 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, cache, or file IO
+ calls).</p></li>
+<li>
+ <p><code class="function">INKMutexLock</code> might <u>not</u> be necessary if
+ you are not making blocking calls and if you are only accessing
+ local resources.</p></li>
+</ul></div>
+<p>The Traffic Server API uses the <code class="function">INKMutex</code> type for
+ a mutex. There are two typical uses of mutex. One use is for locking global
+ data or data shared by various continuations. The other typical usage is
+ for locking data associated with a continuation (i.e., 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
+ a mutex that locks global data. 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>. For more detailed information, see the <a href="App_SampleSourceCode.html#Sample_blacklist-1.c" title="blacklist-1.c"><code>blacklist-1.c</code></a> <code class="filename"></code> code; start by looking at the <a href="InitializationFunctions.html#INKPluginInit" title="INKPluginInit"><code class="code">INKPluginInit</code></a> function. </p>
+<p>General guidelines for locking shared data are as follows:</p>
+<div class="orderedlist"><ol type="1">
+<li>
+ <p>Create a mutex for the shared data with <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"><code>INKMutexUnlock</code></a>. If you are
+ unlocking data accessed during the processing of an HTTP
+ transaction, then you must unlock it before calling <a href="HTTPTransactionFunctions.html#INKHttpTxnReenable" title="INKHttpTxnReenable"><code>INKHttpTxnReenable</code></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 must create a mutex to protect a continuation's data if
+ it might be accessed by other continuations or processes. Here's how:</p>
+<div class="orderedlist"><ol type="1">
+<li>
+<p>Create a mutex for the continuation using
+ <code class="function">INKMutexCreate</code>. <br /> For example:</p>
+<pre class="programlisting">INKMutex mutexp;
+mutexp = INKMutexCreate ();</pre>
+</li>
+<li>
+When you create the continuation, specify this mutex as the
+ continuation's mutex. <br /> For example:
+<pre class="programlisting">INKCont contp;
+contp = INKContCreate (handler, mutexp);</pre>
+</li>
+</ol></div>
+<p>If any other functions want to access <code>contp</code>'s data, then it is up to
+ them to get <code>contp</code>'s mutex (using, for example, <code class="function">INKContMutexGet</code>) to lock it. For usage, ssee the sample
+ Protocol plugin.</p>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div>
+ <h3 class="title">
+<a name="AssocContinuationToHTTPTx"></a>How to Associate a Continuation With Every HTTP
+ Transaction</h3></div></div></div>
+<p>There could be several reasons why you'd want to create a continuation for each
+ HTTP transaction that calls back your plugin. <br />
+ Some potential scenarios
+ are listed below.</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p>You want to register hooks locally with the new continuation instead of
+ registering them globally to the continuation plugin.</p></li>
+<li>
+ <p>You want to store data specific to each HTTP transaction that you might
+ need to reuse across various hooks.</p></li>
+<li>You're using APIs (like <code class="function">INKHostLookup</code>) that
+ will call back the continuation with a certain event.</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 by registering 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, which uses 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 then 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>Remember that the <code class="code">txn_contp</code> handler must destory itself when the HTTP transaction is
+ closed. If you forget to do this, then your plugin will have a memory leak.</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></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 <code>txn_contp</code> data
+ structure - this means that you'll create your own data structure.
+ Now suppose you want to store the state of the HTTP transaction:</p>
+<pre class="programlisting"> typedef struct {
+ int state;
+ } ContData;</pre>
+<p>You need to allocate the memory and initialize this
+ structure for each HTTP <code>txnp</code>. 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>
+</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's 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 one that 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 finished, <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. In general, a lock is needed when you're using iocore APIs
+ or any other API where <code class="code">txn_contp</code> is scheduled to be
+ called back by a processor (such as the cache processor, the DNS
+ processor, etc.). This ensures that
+ <code class="code">txn_contp</code> is called back sequentially and not simultaneously. In other words,
+ you need to ensure that <code class="code">txn_contp</code> will not be called back by
+ both <code class="code">txnp</code> and the cache processor at the same time,
+ since this will result in a situation wherein you're 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, then you probably don't need to create a new mutex for it
+ because each HTTP transaction (<code class="code">INKHttpTxn</code> object) already
+ has its own mutex.</p>
+<p>In the example below, it's 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 listed below:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="MutexFunctions.html#INKMutexCreate" title="INKMutexCreate"><code>INKMutexCreate</code></a></li>
+<li><code><a href="INKMutexLock.html" title="INKMutexLock">INKMutexLock</a></code></li>
+<li><code><a href="INKMutexLockTry.html" title="INKMutexLockTry">INKMutexLockTry</a></code></li>
+</ul></div>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/MutexGuide.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NamingConventions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/NamingConventions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/NamingConventions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,52 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Naming Conventions</title>
+<!--#include file="top.html" -->
+<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">
+<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. <b>Examples</b>: <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.
+ <b>Examples</b>: <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 uppercase; enumerated values can be
+ seen as a subset of constants. <b>Examples</b>: <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. <b>Examples</b>: <em class="parameter"><code>INKHttpSsn</code></em> and
+ <em class="parameter"><code>INKHttpTxn</code></em></p></li>
+<li>
+ <p>Function names are mixed-case. <b>Examples</b>: <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. <b>For</b> <b>example</b>: 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: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NamingConventions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetVconnections.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetVconnections.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetVconnections.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,28 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Net Vconnections</title>
+<!--#include file="top.html" -->
+<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">
+<a name="NetVconnections"></a>Net Vconnections</h2></div></div></div>
+<p>A <b>network</b> <b>vconnection</b> (or<b> netvconnection</b>) is a wrapper around a TCP
+ socket that enables the socket to work within the Traffic Server
+ vconnection framework. See <a href="IOGuide.html#Vconnections" title="Vconnections">vconnections</a> for more
+ information about the Traffic Server abstraction for doing asynchronous
+ IO.</p>
+<p>The netvconnection functions are listed below:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="NetvconnectionFunctions.html#INKNetAccept" title="INKNetAccept">INKNetAccept</a></li>
+<li><a href="INKNetConnect.html" title="INKNetConnect">INKNetConnect</a></li>
+</ul></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetVconnections.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetvconnectionFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetvconnectionFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetvconnectionFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,76 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Netvconnection Functions</title>
+<!--#include file="top.html" -->
+<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">
+<a name="NetvconnectionFunctions"></a>Netvconnection Functions</h2></div></div></div>
+
+
+<ul><b>
+<li><a href="NetvconnectionFunctions.html#INKNetAccept">INKNetAccept</a></li>
+<li><a href="INKNetConnect.html">INKNetConnect</a></li>
+<li><a href="INKNetVConnRemoteIPGet.html">INKNetVConnRemoteIPGet</a></li>
+<li><a href="INKNetVConnRemotePortGet.html">INKNetVConnRemotePortGet</a></li>
+
+</b>
+</ul>
+
+<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"><b>Prototype</b></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"><b>Arguments</b></span></dt>
+<dd>
+<p><code class="function">INKCont</code>
+ <code class="code"><em class="replaceable"><code>contp </code></em></code> is the
+ continuation that's 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
+ that will listen for incoming TCP/IP connections.</p>
+</dd>
+<dt><span class="term"><b>Description</b></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 the event is <code class="code">INK_EVENT_NET_ACCEPT</code>, then 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
+ netvconnection datatype that represents the connection.</p>
+<p>If the event is <code class="code">INK_EVENT_NET_ACCEPT_FAILED</code>, then it
+ means a connection attempt 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 <code>INKNetAccept</code> by
+ using <code class="function">INKActionCancel</code>.</p>
+</dd>
+<dt><span class="term"><b>Returns</b></span></dt>
+<dd>
+<p>An <code>INKAction</code> object if successful.</p>
+<p><code class="code">INK_ERROR_PTR</code> if an argument was incorrect or
+ if the API failed.</p>
+</dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NetvconnectionFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NewProtocolPlugins.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/NewProtocolPlugins.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/NewProtocolPlugins.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,363 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 6. New Protocol Plugins</title>
+<!--#include file="top.html" -->
+<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>
+
+<p><b>Table of Contents</b></p>
+<ul>
+<li><span class="section"><a href="NewProtocolPlugins.html#ProtocolPluginStructure">Protocol Plugin Structure</a></span></li>
+<li><span class="section"><a href="NewProtocolPlugins.html#ContinuationsInProtocolPlugin">Continuations in the Protocol Plugin</a></span></li>
+<li><span class="section"><a href="NewProtocolPlugins.html#EventFlow">Event Flow</a></span></li>
+<li><span class="section"><a href="NewProtocolPlugins.html#ImplementTransStMachine">One Way to Implement a Transaction State Machine</a></span></li>
+<li><span class="section"><a href="NewProtocolPlugins.html#ProcTypicalTransaction">Processing a Typical Transaction</a></span></li>
+</ul>
+
+<p>The new protocol APIs enable you to extend Traffic Server to be a web
+ proxy for any protocol. This chapter describes new protocol APIs and
+ the plugins that support new protocols. It also provides a detailed review of code for a sample Protocol plugin
+ that supports a very simple
+ artificial HTTP-like protocol.</p>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="AboutSampleProtocol"></a>About the Sample Protocol</h2></div></div></div>
+<p>The sample protocol enables a client to ask a server for a file.
+ Clients send requests to a specific Traffic Server port (specified in
+ <code>plugin.config</code>); each request has the following structure:</p>
+<p><span><strong class="command"><code>server_name file_name\n\n</code></strong></span></p>
+<p>Using the Protocol plugin, Traffic Server can accept these
+ requests, parse them, and act as a proxy cache (i.e., request the file from
+ the origin server on the client's behalf and store copies of
+ response messages in cache). The Protocol plugin is a state machine
+ that flows through the states illustrated in the <a href="NewProtocolPlugins.html#Fig_SampleProtocolStDiag" title="Figure 6.1. Sample Protocol State Diagram">Sample Protocol State Diagram</a>. This figure illustrates the steps that
+ Traffic Server and the Protocol plugin go through in order to support the sample
+ protocol. </p>
+<p>In more specific terms, 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 <code>plugin.config</code>)</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 content from 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 <code>plugin.config</code>)</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 some broader concepts. This section assumes you're familiar with the
+ concepts of <b>continuation</b>, Traffic Server's <b>asynchronous event model</b>,
+ and basic Traffic Server <b>plugin structure</b>. If you are not familiar with these concepts, then reference <a href="GetingStarted.html#GettingStarted">Getting Started</a> and <a href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">How to Create Traffic Server Plugins</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
+ <i>"</i><b>accept" state machine</b> - that is, 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. It then creates a new continuation: a transaction state
+ machine. The accept state machine creates one transaction state
+ machine for each transaction (where a <b>transaction</b> consists of a client
+ request and Traffic Server's response). Each transaction state machine
+ lives until the transaction completes; then it is destroyed. If
+ the client's request for content is a cache miss, then a transaction state
+ machine might need to open a connection to the origin server. This is
+ illustrated in the <a href="NewProtocolPlugins.html#Fig_ProtocolPluginOverview" title="Figure 6.2. Protocol Plugin Overview">Protocol Plugin Overview</a> diagram below.</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>The first steps for writing the Protocol plugin are now clear:
+ in <code>INKPluginInit</code>, 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>Below is a summary of the continuations implemented for the
+ Protocol plugin:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p>An <b>accept state machine</b> that listens for client connections,
+ and then 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><b>Transaction state machines</b> that read client requests,
+ process them, and are then destroyed when the transaction is
+ finished.</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>Implementing the rest of the Protocol plugin
+ requires that you understand the flow of events during the
+ course of a transaction. Unlike HTTP transaction plugins, this plugin
+ must read data from network connections and then read/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. 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 therefore be
+ able to handle that event.</p>
+<p>The transaction state machines are activated when the client
+ connection receives incoming request data. The <b>Net Processor</b> notifies
+ the transaction state machine of incoming data. The transaction state
+ machine reads the data; when finished, it initiates a cache
+ lookup of the requested file. When the cache lookup completes, the
+ transaction state machine is activated by the Traffic Server <b>Cache
+ Processor</b>.</p>
+<p>If the transaction state machine needs to open a connection to the
+ origin server to fetch content (in the case of a cache miss), then 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 <b>Host Database Processor</b>. If the transaction must connect to the origin server, then the
+ transaction state machine initiates a net connection and waits for an
+ event from the 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 the <a href="NewProtocolPlugins.html#Fig_ProtocolPluginFlow" title="Figure 6.3. Protocol Plugin Flow of Events">Protocol Plugin Flow of Events</a> diagram above. The thin straight lines show Net
+ Processor event flow, the thin dashed lines represent Host Database event flow,
+ and the thick dashed lines show Cache event flow.</p>
+<p>Notice that this flow of events is independent of the Protocol plugin's design (i.e., whether you build <b>accept</b> or <b>transaction</b>
+ state machines). 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 the 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 the Cache Processor and Traffic Server event
+ system. Similarly, any plugin that does DNS lookups receives events
+ from the Host Database 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><b>Transaction state machines</b> (<b>TSMs</b>) in the Protocol plugin
+ must do the following: </p>
+<div class="itemizedlist"><ul type="disc">
+<li><p>Keep track of the state of the transaction</p></li>
+<li>
+ <p>Handle events received (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>Below is one way you can implement TSMs. Details about how the
+ Protocol plugin does this are provided 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 steps below describe the flow of execution illustrated in <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin">"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"><b>main_handler</b></code>
+ in the Protocol plugin) receives events from the TSM.</p></li>
+<li><p><code class="code"><b>main_handler</b></code> examines the state of the
+ transaction-in particular, it examines the current handler.</p></li>
+<li>
+ <p><code class="code"><b>main_handler</b></code> calls the
+ <code class="code"><b>current_handler</b></code> (which is one of the state handler
+ functions), and then passes the current event to <code class="code"><b>current_handler</b></code>. <br />In <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin">Figure 6.4</a> below, the
+ current handler is called <code class="code"><b>state2_handler</b></code>.</p></li>
+<li>
+ <p>The <code class="code"><b>current_handler</b></code> handles the event and
+ updates the data. <br />
+ In <a href="NewProtocolPlugins.html#Fig_ImplementTransStMachine" title="Figure 6.4. How Transaction State Machines are Implemented in the
+ Protocol Plugin">Figure 6.4</a> below, the state is changed
+ from <code class="code"><b>state2</b></code> to <code class="code"><b>state3</b></code> (and the current
+ handler is changed from <code class="code"><b>state2_handler</b></code> to
+ <code class="code"><b>state3_handler</b></code>).<br /> The next time
+ <code class="code"><b>main_handler</b></code> receives an event, it will be processed
+ by <code class="code"><b>state3_handler</b></code>.</p></li>
+<li>
+ <p><code class="code"><b>state2_handler</b></code> arranges the next callback of
+ the TSM. Typically, it gives Traffic Server additional work to do
+ (such as writing a file to cache)so that it can progress to the
+ next state.<br />
+The TSM (<code class="code"><b>main_handler</b></code>) then waits for the
+ next event to arrive from Traffic Server.</p></li>
+</ol></div>
+
+<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>Below is a step-by-step walk-through of the code that processes a typical transaction.</p>
+<div class="orderedlist"><ol type="1">
+<li>
+ <p>The <code class="function">INKPluginInit</code> function is in the
+ <code class="filename">Protocol.c</code> file. It checks the validity of the
+ <code>plugin.config</code> 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"><b>init</b></code> function (in
+ <code class="filename">Protocol.c</code>) creates the plugin's log file
+ using <code class="code"><b>INKTextLogObjectCreate</b></code>.</p></li>
+<li>
+ <p>The <code class="function"><b>init</b></code> function creates the accept
+ state machine using <code class="code"><b>AcceptCreate</b></code>. The code for
+ <code class="code"><b>AcceptCreate</b></code> is in the
+ <code class="filename">Accept.c</code> file.</p></li>
+<li>
+ <p>The accept state machine, like the transaction state
+ machine, keeps track of its state with a data structure. This data
+ structure, <code><b>Accept</b></code>, is defined in the <code class="filename">Accept.h</code> file. State data in <code><b>AcceptCreate</b></code> is associated with the new
+ accept state machine via <code class="code"><b>INKContDataSet</b></code>.</p></li>
+<li>
+ <p>The <code class="function"><b>init</b></code> function arranges the callback
+ of the accept state machine when there is a network connection
+ by using <code class="code"><b>INKNetAccept</b></code>.</p></li>
+<li>
+ <p>The handler for the accept state machine is
+ <code class="function"><b>accept_event</b></code> in the
+ <code class="filename">Accept.c</code> file. When Traffic Server's Net Processor
+ sends <code class="code"><b>INK_EVENT_NET_ACCEPT</b></code> to the accept state
+ machine, <code class="function"><b>accept_event</b></code> creates a transaction
+ state machine (<code class="code"><b>txn_sm</b></code>) by calling
+ <code class="code"><b>TxnSMCreate</b></code>. <br />
+ Notice that
+ <code class="function"><b>accept_event</b></code> creates a mutex for the
+ transaction state machine, since each transaction state machine has its
+ own mutex.</p></li>
+<li>
+ <p>The <code class="function"><b>TxnSMCreate</b></code> function is in the
+ <code class="filename">TxnSM.c</code> file. The first thing it does is
+ initialize the transaction's data, which is of type
+ <code class="code">TxnSM</code> (as defined in <code class="filename">TxnSM.h</code>).
+ <br />Notice that the current handler (<code class="code"><b>q_current_handler</b></code>)
+ is set to <code class="code"><b>state_start</b></code>.</p></li>
+<li>
+ <p><code class="function"><b>TxnSMCreate</b></code> then creates a transaction
+ state machine using <code class="code"><b>INKContCreate</b></code>. The handler for
+ the transaction state machine is <code class="code"><b>main_handler</b></code>, which is in the <code class="filename">TxnSM.c</code> file.</p>
+</li>
+<li>
+ <p>When <code class="function"><b>accept_event</b></code> receives
+ <code class="code"><b>INK_EVENT_NET_ACCEPT</b></code>, it calls the transaction state
+ machine ( <code class="code"><b>INKContCall</b></code><b> (<code class="code">txn_sm, 0,
+ NULL);</code></b> ). The event passed to
+ <code class="function"><b>main_handler</b></code> is <code>0</code> (<code class="code"><b>INK_EVENT_NONE</b></code>).</p></li>
+<li><p>The first thing <code class="function"><b>main_handler</b></code> does is
+ examine the current <code class="code"><b>txn_sm</b></code> state by calling
+ <code class="code"><b>INKContDataGet</b></code>. The state is
+ <code class="code"><b>state_start</b></code>.</p></li>
+<li>
+ <p><code class="code"><b>main_handler</b></code> then invokes the handler for
+ <code><b>state_start</b></code> by using the function pointer <code class="function"><b>TxnSMHandler</b></code> (as defined in
+ <code class="filename">TxnSM.h</code>).</p></li>
+<li>
+ <p>The <code class="function"><b>state_start</b></code> handler function (in the
+ <code class="filename">TxnSM.c</code> file) is handed an event (at this stage,
+ the event is <code class="code"><b>INK_EVENT_NET_ACCEPT</b></code>) and a client
+ vconnection. <br />
+ <code class="function"><b>state_start</b></code> checks to see if
+ this client vconnection is closed; if it is not, then
+ <code class="function"><b>state_start</b></code> attempts to read data from the
+ client vconnection into an <code class="code"><b>INKIOBuffer</b></code> (<code class="function"><b>state_start</b></code> is handling the event it
+ receives).</p></li>
+<li>
+ <p><code class="function"><b>state_start</b></code> changes the current handler
+ to <code class="function"><b>state_interface_with_client</b></code> (that is, it updates the
+ state of the transaction to the next state).</p></li>
+<li>
+ <p><code class="function"><b>state_start</b></code> initiates a read of the
+ client vconnection (arranges for Traffic Server to send
+ <code class="code"><b>INK_EVENT_VCONN_READ_READY</b></code> events to the TSM) by
+ calling <code class="code"><b>INKVConnRead</b></code>.</p></li>
+<li>
+ <p><code class="function"><b>state_interface_with_client</b></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"><b>INKVConnRead</b></code>.</p></li>
+<li>
+ <p>If the read VIO is the <code class="code"><b>client_read_VIO</b></code> (which
+ we are expecting at this stage in the transaction), then
+ <code class="function"><b>state_interface_with_client</b></code> updates the state
+ to <code class="function"><b>state_read_request_from_client</b></code> .</p></li>
+<li>
+ <p><code class="function"><b>state_read_request_from_client</b></code> handles
+ actual <code class="code"><b>INK_EVENT_READ_READY</b></code> events and reads the
+ client request.</p></li>
+<li>
+ <p><code class="function"><b>state_read_request_from_client</b></code> parses
+ the client request.</p></li>
+<li>
+ <p><code class="function"><b>state_read_request_from_client</b></code> updates
+ the current state to the next state,
+ <code class="function"><b>state_handle_cache_lookup</b></code> .</p></li>
+<li>
+ <p><code class="function"><b>state_read_request_from_client</b></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"><b>INKCacheRead</b></code>.</p></li>
+<li>
+ <p>When the <code class="code"><b>INKCacheRead</b></code> sends the TSM either
+ <code class="code"><b>INK_EVENT_OPEN_READ</b></code> (a cache hit) or
+ <code class="code"><b>INK_EVENT_OPEN_READ_FAILED</b></code> (a cache miss),
+ <code class="function"><b>main_handler</b></code> calls
+ <code class="function"><b>state_handle_cache_lookup</b></code>.</p></li>
+</ol></div>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/NewProtocolPlugins.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/OtherDeprecatedFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/OtherDeprecatedFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/OtherDeprecatedFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,83 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Other Deprecated Functions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="App_DeprecatedFunctions.html">Prev</a> - Appendix B. Deprecated Fxns - MIME Header Fxns</div>
+<div class="navnext">Deprecated IO Buffer Interface Fxns- <a accesskey="n" href="Dep_IOBufferInterface.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="OtherDeprecatedFunctions"></a>Other Deprecated Functions</h2></div></div></div>
+<p><b>Table Of Contents</b></p>
+
+<ul><b>
+ <li><a href="OtherDeprecatedFunctions.html#Dep_StatisticFunctions">Statistics Functions</a></li>
+<ul>
+<li><a href="OtherDeprecatedFunctions.html#INKStatFloatRead">INKStatFloatRead</a></li>
+<li><a href="OtherDeprecatedFunctions.html#INKStatIntRead">INKStatIntRead</a></li>
+</ul>
+
+<li><a href="Dep_IOBufferInterface.html"> IO Buffer Interface Functions</a></li>
+<ul>
+<li><a href="Dep_IOBufferInterface.html#INKIOBufferAppend">INKIOBufferAppend</a></li>
+<li><a href="Dep_IOBufferInterface.html#INKIOBufferBlockCreate">INKIOBufferBlockCreate</a></li>
+ <li><a href="Dep_IOBufferInterface.html#INKIOBufferDataCreate">INKIOBufferDataCreate</a></li>
+ </ul>
+
+
+
+<li><a href="Dep_MutexFunctions.html"> Mutex Functions</a></li>
+<ul>
+ <li><a href="Dep_MutexFunctions.html#INKMutexTryLock">INKMutexTryLock</a></li>
+ </ul>
+</b>
+</ul>
+
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div>
+ <h3 class="title">
+<a name="Dep_StatisticFunctions"></a>Deprecated Statistics Functions</h3></div></div></div>
+
+
+<ul><b>
+<li><a href="OtherDeprecatedFunctions.html#INKStatFloatRead">INKStatFloatRead</a></li>
+<li><a href="OtherDeprecatedFunctions.html#INKStatIntRead">INKStatIntRead</a></li>
+</b>
+</ul>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatFloatRead"></a>INKStatFloatRead</h4></div></div></div>
+<p>Obtains the value of a float statistic. This API has been succeeded by
+ <code class="function">INKStatFloatGet</code>.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd>
+<p><code class="code">float INKStatFloat(INKStat
+ <em class="replaceable"><code>the_stat</code></em> )</code></p>
+</dd>
+</dl></div>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h4 class="title">
+<a name="INKStatIntRead"></a>INKStatIntRead</h4></div></div></div>
+<p>Obtains the value of an integer statistic. This API has been succeeded by
+ <code class="function">INKStatIntGet</code>.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd>
+<p><code class="code">INK64 INKStatIntRead(INKStat
+ <em class="replaceable"><code>the_stat</code></em> )</code></p>
+</dd>
+</dl></div>
+</div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/OtherDeprecatedFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurationFunctions.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurationFunctions.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurationFunctions.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,49 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Plugin Configuration Functions</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="INKContSchedule.html">Prev</a> - INKContSchedule</div>
+<div class="navnext">INKConfigGet - <a accesskey="n" href="INKConfigGet.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="PluginConfigurationFunctions"></a>Plugin Configuration Functions</h2></div></div></div>
+
+
+<ul><b>
+<li><a href="PluginConfigurationFunctions.html#INKConfigDataGet">INKConfigDataGet</a></li>
+<li><a href="INKConfigGet.html">INKConfigGet</a></li>
+<li><a href="INKConfigRelease.html">INKConfigRelease</a></li>
+<li><a href="INKConfigSet.html">INKConfigSet</a></li>
+</b>
+</ul>
+
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="INKConfigDataGet"></a>INKConfigDataGet</h3></div></div></div>
+<p>Gets configuration data.</p>
+<div class="variablelist"><dl>
+<dt><span class="term"><b>Prototype</b></span></dt>
+<dd><p><code class="code">void* INKConfigDataGet (INKConfig
+ <em class="replaceable"><code>configp</code></em>)</code></p></dd>
+<dt><span class="term"><b>Description</b></span></dt>
+<dd>
+ <p>Retrieves the data pointer from within the configuration
+ pointer <code class="code"><em class="replaceable"><code>configp</code></em></code>. Before
+ using <code class="function">INKConfigDataGet</code>, you must give the
+ configuration data an identifier with
+ <code class="function">INKConfigSet</code> and then retrieve the
+ <code class="function">INKConfig</code> pointer
+ <code class="code"><em class="replaceable"><code>configp </code></em></code> with a call to
+ <code class="function">INKConfigGet</code> (see the code snippet in the
+ previous section).</p></dd>
+</dl></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurationFunctions.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurations.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurations.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurations.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,99 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 13. Plugin Configurations</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="WritingHandlerFunctions.html">Prev</a> - Writing Handler Functions</div>
+<div class="navnext">Chapter 14. Actions Guide - <a accesskey="n" href="ActionsGuide.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="PluginConfigurations"></a>Chapter 13. Plugin Configurations</h2></div></div></div>
+<p>This chapter contains the following section:</p>
+<div class="itemizedlist"><ul type="disc"><li><p><a href="PluginConfigurations.html#Plugin_Configs" title="Plugin Configurations">Plugin Configurations</a></p></li></ul></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Plugin_Configs"></a>Plugin Configurations</h2></div></div></div>
+<p>The <code class="function">INKConfig</code> family of functions provides a
+ mechanism for accessing and changing global configuration information
+ within a plugin.</p>
+<p>The functions discussed in this section do not examine or modify
+ Traffic Server configuration variables. To examine Traffic Server
+ configuration and statistics variables, see <a href="ReadTESettingStats.html" title="Reading Traffic Server Settings and Statistics">"Reading Traffic Server Settings and Statistics"</a>.</p>
+<p>The <code class="function">INKConfig</code> family of functions is designed
+ to provide a fast and efficient mechanism for accessing and changing
+ global configuration information within a plugin. Such a mechanism is
+ simple enough to provide in a single-threaded program, but the
+ translation to a multi-threaded program such as Traffic Server is
+ difficult. A common technique is to have a single mutex protect the
+ global configuration information; however, the problem with this solution is that
+ a single mutex becomes a performance bottleneck very quickly.</p>
+<p>The <code class="function">INKConfig</code> family of functions define an
+ interface to storing and retrieving an opaque data pointer. Internally,
+ Traffic Server maintains reference count information about the data
+ pointer so that a call to <code class="function">INKConfigSet</code> will not
+ disturb another thread using the current data pointer. The philosophy is
+ that once a user has a hold of the configuration pointer, it is okay for
+ it to be used even if the configuration changes; all that a user typically wants is a non-changing snapshot of the
+ configuration. You should use
+ <code class="function">INKConfigSet</code> for all global data updates.</p>
+<p>Here's how the interface works:</p>
+<pre class="programlisting">/* Assume that you have previously defined a plugin configuration
+ * data structure named ConfigData, along with its constructor
+ * plugin_config_allocator () and its destructor
+ * plugin_config_destructor (ConfigData *data)
+ */
+ConfigData *plugin_config;
+
+/* You will need to assign plugin_config a unique identifier of type
+ * unsigned int. It is important to initialize this identifier to zero
+ * (see the documentation of the function).
+ */
+static unsigned int my_id = 0;
+
+/* You will need an INKConfig pointer to access a snapshot of the
+ * current plugin_config.
+ */
+INKConfig config_ptr;
+
+/* Initialize plugin_config. */
+plugin_config = plugin_config_allocator();
+
+/* Assign plugin_config an identifier using INKConfigSet. */
+my_id = INKConfigSet (my_id, plugin_config, plugin_config_destructor);
+
+/* Get a snapshot of the current configuration using INKConfigGet. */
+config_ptr = INKConfigGet (my_id);
+
+/* With an INKConfig pointer to the current configuration, you can
+ * retrieve the configuration's current data using INKConfigDataGet.
+ */
+plugin_config = (ConfigData*) INKConfigDataGet (config_ptr);
+
+/* Do something with plugin_config here. */
+
+/* When you are done with retrieving or modifying the plugin data, you
+ * release the pointers to the data with a call to INKConfigRelease.
+ */
+INKConfigRelease (my_id, config_ptr);
+
+/* Any time you want to modify plugin_config, you must repeat these
+ * steps, starting with
+ * my_id = INKConfigSet (my_id,plugin_config, plugin_config_destructor);
+ * and continuing up to INKConfigRelease.
+ */</pre>
+<p>The configuration functions are:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><code class="function"><a href="PluginConfigurationFunctions.html#INKConfigDataGet" title="INKConfigDataGet">INKConfigDataGet</a></code></p></li>
+<li><p><code class="function"><a href="INKConfigGet.html" title="INKConfigGet">INKConfigGet</a></code></p></li>
+<li><p><code class="function"><a href="INKConfigRelease.html" title="INKConfigRelease">INKConfigRelease</a></code></p></li>
+<li><p><code class="function"><a href="INKConfigSet.html" title="INKConfigSet">INKConfigSet</a></code></p></li>
+</ul></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginConfigurations.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginManagement.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginManagement.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginManagement.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,48 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Chapter 16. Plugin Management</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="CacheAPI_Example.html">Prev</a> - Example</div>
+<div class="navnext">Reading Traffic Server Settings and Statistics - <a accesskey="n" href="ReadTESettingStats.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="chapter" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="PluginManagement"></a>Chapter 16. Plugin Management</h2></div></div></div>
+<p>This chapter covers the following topics:</p>
+<div class="itemizedlist"><ul type="disc">
+<li>
+ <p><a href="ReadTESettingStats.html" title="Reading Traffic Server Settings and Statistics">Reading Traffic Server Settings and Statistics</a></p>
+ <p>Using the functions in this chapter, plugins read Traffic
+ Server configuration settings and statistics from the <code>records.config</code> file.</p>
+</li>
+<li>
+<p><a href="AccessPluginFiles.html" title="Accessing Installed Plugin Files">Accessing Installed Plugin Files</a></p>
+<p>Put plugin access-related files in the plugin installation
+ directory and make sure your plugins are preserved during
+ Traffic Server upgrades.</p>
+</li>
+<li><p><a href="LicensingPlugin.html" title="Licensing Your Plugin">Licensing Your Plugin</a></p>
+ <ul>
+ <li><a href="SetUpLicensing.html">Setting Up Licensing</a></li>
+ <li><a href="GenerateLicenseKey.html">Generating a License Key</a></li>
+ </ul>
+</li>
+<li>
+<p><a href="LoggingAPI.html" title="Guide to the Logging API">Guide to the Logging API</a></p>
+<p>The logging API enables your plugin to log text entries in a
+ custom Traffic Server log file. This section provides a basic overview of
+ the logging interface.</p>
+</li>
+</ul>
+</div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div></div></div></div>
+</div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PluginManagement.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PlusingRegisAndVersionCkg.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/PlusingRegisAndVersionCkg.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/PlusingRegisAndVersionCkg.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,81 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Plugin Registration and Version Checking</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="RestartingTS.html">Prev</a> - Restart Traffic Server</div>
+<div class="navnext">Naming Conventions - <a accesskey="n" href="NamingConventions.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="PlusingRegisAndVersionCkg"></a>Plugin Registration and Version Checking<a class="indexterm" name="id307848"></a></h2></div></div></div>
+<p>Make sure that the functions in your plugin are
+ supported in your version of Traffic Server.</p>
+
+<p>Use the following interfaces:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><a href="INKPluginRegister.html" title="INKPluginRegister">INKPluginRegister</a></li>
+<li><a href="INKTrafficServerVersionGet.html" title="INKTrafficServerVersionGet">INKTrafficServerVersionGet</a></li>
+</ul></div>
+<p>The following version of <code class="filename">hello-world</code>
+ registers the plugin and ensures it's running with a compatible version
+ of Traffic Server.<a class="indexterm" name="id324299"></a></p>
+<pre class="programlisting">#include <stdio.h>
+#include <ts/ts.h>
+int
+check_ts_version()
+{
+
+ const char *ts_version = INKTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* We need at least Traffic Server 2.0 */
+
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+}
+
+void
+INKPluginInit (int argc, const char *argv[])<a class="indexterm" name="id324315"></a>
+{
+
+ INKPluginRegistrationInfo info;
+
+ info.plugin_name = "hello-world";
+ info.vendor_name = "MyCompany";
+ info.support_email = "ts-api-support@MyCompany.com";
+
+ if (!INKPluginRegister (INK_SDK_VERSION_2_0 , &info)) {
+ INKError ("Plugin registration failed. \n");
+ }
+
+ if (!check_ts_version()) {
+ INKError ("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ INKDebug ("debug-hello", "Hello World!\n");
+}</pre>
+</div>
+</body>
+</html>
+
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/PlusingRegisAndVersionCkg.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/Preface.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/Preface.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/Preface.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,45 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Preface</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="index.html">Prev</a> - Traffic Server Software Developers Kit</div>
+<div class="navnext">How to Use This Book - <a accesskey="n" href="pr01s02.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="preface" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Preface"></a>Preface</h2></div></div></div>
+<div class="toc">
+<p><b>Table of Contents</b></p>
+<dl>
+<dt><span class="section"><a href="Preface.html#Audience"></a></span></dt>
+<dt><span class="section"><a href="pr01s02.html">How to Use This Book</a></span></dt>
+<dt><span class="section"><a href="Conventions.html">Typographical Conventions</a></span></dt>
+</dl>
+</div>
+<p>The <span class="emphasis"><em>Traffic Server Software Developer's Kit</em></span> is a
+ reference for creating plugins. <b>Plugins</b> are programs that add services
+ (such as filtering or content transformation) or entire features (such as
+ new protocol support) to Traffic Server. If you are new to writing Traffic
+ Server plugins, then read the first two chapters, <a href="GetingStarted.html#GettingStarted">Getting Started</a> and <a href="CreatingTSPlugins.html" title="Chapter 2. How to Create Traffic Server Plugins">Creating Traffic Server Plugins</a>, and
+ use the remaining chapters as needed. <a href="HeaderBasedPluginEx.html" title="Chapter 4. Header-Based Plugin Examples">Header-Based Plugin Examples</a> provides
+ details about plugins that work on HTTP headers, while <a href="HTTPTransformationPlugins.html" title="Chapter 5. HTTP Transformation Plugins">HTTP Transformation Plugins</a>
+ explains how to write a plugin that transforms or scans the body of an
+ HTTP response. If you want to support your own protocol on Traffic Server,
+ then reference <a href="NewProtocolPlugins.html" title="Chapter 6. New Protocol Plugins">New Protocol Plugins</a>.</p>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="Audience"></a>Audience</h2></div></div></div>
+<p>This manual is intended for programmers who want to write plugin
+ programs that add services or features to Traffic Server. It assumes a
+ cursory knowledge of the C programming language, Hyper-Text Transfer
+ Protocol (HTTP), and Multipurpose Internet Mail Extensions
+ (MIME).</p>
+</div>
+</div>
+</body>
+</html>
\ No newline at end of file
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/Preface.html
------------------------------------------------------------------------------
svn:executable = *
Added: websites/staging/trafficserver/trunk/content/docs/v2/sdk/ReadTESettingStats.html
==============================================================================
--- websites/staging/trafficserver/trunk/content/docs/v2/sdk/ReadTESettingStats.html (added)
+++ websites/staging/trafficserver/trunk/content/docs/v2/sdk/ReadTESettingStats.html Tue Dec 24 18:32:14 2013
@@ -0,0 +1,51 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<title>Reading Traffic Server Settings and Statistics</title>
+<!--#include file="top.html" -->
+<div class="navheader">
+<div class="navprev">
+<a accesskey="p" href="PluginManagement.html">Prev</a> - Chapter 16. Plugin Management</div>
+<div class="navnext">Accessing Installed Plugin Files - <a accesskey="n" href="AccessPluginFiles.html">Next</a>
+</div>
+</div>
+<div id="toc"></div>
+<div class="section" lang="en">
+<div class="titlepage"><div><div><h2 class="title">
+<a name="ReadTESettingStats"></a>Reading Traffic Server Settings and Statistics</h2></div></div></div>
+<p>Your plugin might need to know information about Traffic Server's
+ current configuration and performance. The functions described in this
+ section read this information from the Traffic Server
+ <code class="filename">records.config</code> file. Configuration settings are
+ stored in <code class="varname">CONFIG</code> variables and statistics are stored
+ in <code class="varname">PROCESS</code> variables.</p>
+<div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Caution">
+<tr>
+<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="images/docbook/caution.png" /></td>
+<th align="left">Caution</th>
+</tr>
+<tr><td align="left" valign="top"><p>Not all <code class="varname">CONFIG</code> and <code class="varname">PROCESS</code>
+ variables in <code>records.config</code> are relevant to Traffic Server's
+ configuration and statistics. Therefore, retrieve only the <code>records.config</code> variables that are documented in the <a href="../admin/">Traffic Server Administrator's
+ Guide</a>.</p></td></tr>
+</table></div>
+<p>To retrieve a variable, you need to know its type
+ (<code class="code">int</code>, <code class="code">counter</code>, <code class="code">float</code>, or
+ <code class="code">string</code>). Plugins store the <code>records.config</code> values as an <code class="function">INKMgmtInt</code>, <code class="function">INKMgmtCounter</code>, <code class="function">INKMgmtFloat</code>, or <code class="function">INKMgmtString</code>. You can look up
+ <code class="filename">records.config</code> variable types in the <a href="../admin/">Traffic Server Administrator's Guide</a>.</p>
+<p>Depending on the result type, you'll use
+ <code class="function">INKMgmtIntGet</code>,
+ <code class="function">INKMgmtCounterGet</code>,
+ <code class="function">INKMgmtFloatGet</code>, or
+ <code class="function">INKMgmtStringGet</code> to obtain the variable
+ value (see the example for <a href="INKMgmtIntGet.html" title="INKMgmtIntGet">INKMgmtIntGet</a>).</p>
+<p>The <code class="function">INKMgmt*Get</code> functions are:</p>
+<div class="itemizedlist"><ul type="disc">
+<li><p><a href="TEConfigReadFunctions.html#INKMgmtCounterGet" title="INKMgmtCounterGet">INKMgmtCounterGet</a></p></li>
+<li><p><a href="INKMgmtFloatGet.html" title="INKMgmtFloatGet">INKMgmtFloatGet</a></p></li>
+<li><p><a href="INKMgmtIntGet.html" title="INKMgmtIntGet">INKMgmtIntGet</a></p></li>
+<li><p><a href="INKMgmtStringGet.html" title="INKMgmtStringGet">INKMgmtStringGet</a></p></li>
+</ul></div>
+</div>
+</body>
+</html>
Propchange: websites/staging/trafficserver/trunk/content/docs/v2/sdk/ReadTESettingStats.html
------------------------------------------------------------------------------
svn:executable = *